🛠 Updated on 23rd Feb 2025
This article has been revised based on valuable feedback from readers, thank you all!
Are you tired of juggling multiple tools like pip, virtualenv, conda, poetry, and pyenv just to keep your Python environments and dependencies in check? You’re not alone! Managing Python projects can feel like a headache, especially with all the different package managers and tools you have to wrangle.
Enter uv – The Universal Virtualenv
Think of uv as a one-stop-shop package manager designed to streamline and speed up your Python development process.
A Little Backstory
uv draws its inspiration from Rye, another modern packaging manager, to unify the best features of pip, pip-tools, pyenv, virtualenv, and poetry. Built using Rust, uv is not just fast but highly efficient, simplifying everything from managing dependencies to creating virtual environments.
The Aim of uv
In a nutshell, uv is about consolidation. Why switch between multiple tools when you can have one unified experience? It aims to remove the friction from Python development, offering you a more consistent and faster way to manage your projects. And it’s also blazing fast! That opens new doors for dynamic management.
1. Portable Code with Inline Script Metadata
Let’s Talk Dependencies
One of the most exciting features of uv is the ability to add dependencies directly within your Python script. Imagine you have a simple script like this:
# app.py
import requests
from rich.pretty import pprint
response = requests.get("https://peps.python.org/api/peps.json")
data = response.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])
Running this script usually means setting up a virtual environment and installing dependencies manually. With uv, you can embed all your dependencies directly into the script, making it self-contained and shareable:
uv add --script app.py 'requests<3' 'rich'
Automatic Metadata Generation
This adds metadata to the script file:
# app.py
# /// script
# dependencies = [
# "requests<3",
# "rich",
# ]
# ///
import requests
from rich.pretty import pprint
response = requests.get("https://peps.python.org/api/peps.json")
data = response.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])
And that’s it! You can share this file with someone else, and they can simply run:
uv run app.py
And voilà — no external setup required! All thanks to uv’s speed and efficiency.
2. Creating and Managing Virtual Environments
Getting Started with Virtual Environments
By default, uv requires packages to be installed within virtual environments to keep your system clean and avoid conflicts between different projects. Creating a virtual environment with uv is simple:
uv venv
This will create a .venv directory containing the isolated environment. If you want to specify a custom directory or Python version, you can do:
uv venv my_env --python 3.9
The environment is ready to use, and uv will detect it automatically for all your commands, like installing packages or running scripts.
When to Use uv add vs. uv pip install
✅ Use uv add
When you want to add dependencies to your project’s pyproject.toml file. This is best when you are developing a project and want to keep track of all dependencies.
uv add fastapi
This will update your pyproject.toml and lock the version in uv.lock.
✅ Use uv pip install
When you want to install packages for quick use without modifying the project file or for global tools where you don’t need to track them in a pyproject.toml.
uv pip install requests
Choosing the right command ensures your project is properly managed and easy to share or deploy.
3. Lock Versions for Reproducibility
Ever Had Your Code Break Due to Updates?
We’ve all been there — your code works today, then breaks tomorrow because a package gets updated. With uv, you can prevent this by locking package versions to ensure consistency and reproducibility:
[tool.uv]
exclude-newer = "2023-10-16T00:00:00Z"
This way, even if new versions of your dependencies come out, your project remains stable. Perfect for long-term projects where you can’t afford surprises!
4. Managing Python Versions
Different Projects, Different Python Versions? No Problem!
Many developers work on multiple projects that require different Python versions. uv makes switching versions as easy as:
uv python install 3.8 3.9 3.10
Once the versions are installed, switching between them is seamless:
uv run --python 3.10 app.py
And if you want to lock a specific version for a project:
uv python pin 3.9
No more juggling pyenv commands — uv handles all the heavy lifting for you.
5. Say Goodbye to pip Hassles
It’s pip — but Faster and Better
uv provides a pip-like experience, but with turbocharged performance. Installing packages is straightforward:
uv pip install flask
Need to add optional dependencies or install directly from a GitHub repo? No sweat:
uv pip install 'torch>=1.10.0' "git+https://github.com/astral-sh/ruff"
No more waiting around for slow installations — uv gets the job done fast and effectively.
6. Manage CLI Tools Globally and Easily
From black to ruff, Get Your Tools Hassle-Free
Globally:
uv tool install ruff
Locally within a Project:
uv add ruff
Run Ephemeral Commands without Installing Globally:
uvx black my_code.py
Say goodbye to package conflicts and environment pollution — just run your tools whenever and wherever you need them.
🚀 Ready to Take uv for a Spin?
If you’re looking to supercharge your Python development and want to stop wrestling with multiple tools, uv is your answer.
With its streamlined commands, reproducible environments, and efficient package management, uv makes Python development a pleasure rather than a chore.
📌 Stay tuned for Part 2, where we’ll dive deeper into advanced features like leveraging pyproject.toml, handling global vs. local tool installations, and how uv can be your best friend when managing complex environments.
💡 For full details and documentation, check out uv documentation.
🐍✨ Happy coding!
Top comments (0)