Mastering Python Project Management with uv Part1: it’s Time to Ditch Poetry!

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 it 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 blasing fast! That opens new doors, for [dynamic management](https://www.youtube.com/watch?v=jXWIxk2brfk)

— -

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:

# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

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, making the project easily shareable and reproducible. We will cover this in the next post, stay tuned!

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`. Think of `uv pip` as an immediate, one-off installation.

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 have to 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
Whether you’re linting code or formatting files, `uv` makes installing CLI tools easy:

• 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.

— -

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.

Ready to take `uv` for a spin? 🚀 Start today and experience a better way to manage your Python projects.

— -

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.

Happy coding! 🐍✨

For more details and full documentation, check out [`uv` documentation](https://docs.astral.sh/uv).