UV Tutorial: A Fast Python Package and Project Manager

The team at Astral took the Python world by surprise by releasing a set of incredibly performant tools for development. In just a year, they have introduced:

• uv: A Python project and package manager

• Ruff: A Python linter and code formatter

• Ty: A Python type checker

The buzz is justified, since they have proven their tooling improves development experience significantly for Python coders.

In this tutorial we are going to do a short and sweet intro to uv to manage Python versions, projects and virtual environments.

Fast Pythons, as imagined by ChatGPT.

What is uv?

Uv is a Python project and package manager. What does this even mean? Think of uv as an all-batteries-included replacement for:

• virtualenv, pyenv,

• pip, pip-tools, pipx

• wheel, twine

• poetry, hatch

While there are other alternatives out there (like hatch/hatchling, poetry, conda...), uv has become extremely popular for its remarkable speed and nice ergonomics. As their authors describe it:

An extremely fast Python package and project manager, written in Rust.

Follow the rest of the tutorial for a straight-to-the-point guide on how to get started with uv.

The Way You Should Think of UV

The full trick to understand uv is to not think in terms of regular Python environments. If you are familiar with Node.js or Bun, it might feel more familiar. Essentially, you handle everything through the uv command and it will take care of everything for you.

Just remember to run everything through the uv command

For example, consider the following snippet comparing a regular venv against uv:

# Using a regular virtual environment
source .venv/bin/activate
python3 myscript.py

# Using uv
uv run myscript.py

Of course, there's nothing wrong with entering the environment. It's just not necessary for development purposes.

Installing uv

The simplest way to install uv is by running on your terminal:

curl -LsSf https://astral.sh/uv/install.sh | sh

After installation, restart you terminal and you are ready to go! Test the installation by running:

uv

which should output something like:

An extremely fast Python package manager.

Usage: uv [OPTIONS] <COMMAND>
...

If you want more installation options refer to the documentation.

Running Python Scripts

Uv can simplify the execution of standalone scripts. Even if those have dependencies.

• Run a script. If there is a venv in the directory, it will run it there. Otherwise uv will create a hidden, volatile one and run it in there for you.

uv run myscript.py

• Run a script with a specific Python version:

uv run --python 3.14 myscript.py

• Run a script and automatically install dependencies:

uv run --with numpy --with matplotlib myscript.py

Scripts with Metadata

Uv can also understand special metadata in the script header to automatically infer the dependencies, without needing you to explicitly specify them. The simplest way to understand this is to use uv to create the script.

• Create a script with metadata in it. You can run this over an existing script and it will just add the metadata.

uv init --script myscript.py

• Add the dependencies to the script

uv add --script myscript.py numpy matplotlib

• Run the script. You'll notice there's no need to specify the dependencies anymore.

uv run myscript.py

If you explore the script header you'll now see the metadata at the top:

# /// script
# requires-python = ">=3.14"
# dependencies = [
#     "matplotlib",
#     "numpy",
# ]
# ///

Note that devs not using uv can still run the script without problems.

Managing Python Versions

Of course, uv can work with multiple Python version without the risk of breaking your system!

• List available versions (installed and installable). By default only the highest micro versions for each minor versions will be shown.

uv python list

• List absolutely all versions (installed and installable)

uv python list --all-versions

• Install a specific version. There's no need to specify the full version, uv will figure out the best option for the remainder.

uv python install 3.14

Working with Virtual Environments

Most of the time it is recommended to work with a virtual environment. Uv, again, makes this pretty straightforward.

• Create a virtual environment. By default it will be created in the same directory and be named .venv

uv venv

• Create a virtual environment with a specific Python version.

uv venv --python 3.14

• Install a package in the virtual environment. Of course, you may specify the package version if needed. This will automatically pick the .venv in your directory.

uv pip install numpy

• List installed packages. This will again pick the .venv in your directory.

uv pip list

• Run a tool available in the environment

uv run python3 --version

You'll notice something particular about uv environments: they don't have pip in it. That's deliberate because the packages are supposed to be managed with uv.

Remember to use uv pip instead of standalone pip

Managing Python Projects with UV

Finally, one of my favorite features is the project management.

• Initialize a project. This creates a git repo as well, ready for everything to be commited.

uv init myproject

• Add a dependency to a project. This will correctly add the dependency to the pyproject.toml.

uv add numpy

• Remove a dependency from a project. This will correctly remove the dependency from the pyproject.toml.

uv remove numpy

• Synchronize the venv with the project. This will happen automatically with every uv call, but you might want to run this if you manually edited the pyproject.toml. If the .venv doesnt exist yet, it will be created.

uv sync

• Run the project. You don't have to install the project, uv will automatically install it in editable mode for you.

uv run hello

• Install a dependency marked for development (in the optional dev group).

uv add --dev ruff

• Install a dependency in an optional extra group. For example, to enable a debug dependency run:

uv add --optional debug matplotlib

The project created by uv is a standard pyproject.toml which is the modern recommendation of the Python community.

Don't install your project manually. Uv will install it in editable mode for you. This includes development dependencies.

Don't be afraid of tweaking the pyproject.toml to your needs. Typically uv is very smart about extending it, even if you have modified it. I've never ran into a problem.

Note that devs not using uv can still work with your project normally, using standard Python tooling.

Other Features

There's much more to uv than I explained in this tutorial. I just went through the features I use 90% of the time as a Python developer. See the official documentation for a full walkthrough.

FAQ

• What is uv.lock and why do I need it?

  The lock file is a very explicit file whose purpose is to ensure project reproducibility in a much better way that something like requirements.txt could. The uv.lock has the recursive tree of dependencies solved, and it ensures that the exact set of dependencies (and their dependencies) are resolved to the same versions you are using.

  
  

• Should I version the uv.lock?

  Yes, I recommend it. Other developers using uv will make use of it.

• Do I still need a requirements.txt?

  It depends, but probably yes. Other systems like CI's, HuggingFace, Heroku, etc... still rely on them. Fortunately you can run uv export and will generate the equivalent requirements.txt.

• Why should I use uv instead of hatch, which is developed by the Python community?

  Use the tool that best works for you. The main advantage of uv is it's speed. However, in recent releases of hatch, you can configure uv as the installer backed. My opinion is that the Astral team has gained my trust and their release cycle is extremely fast. That, summed to the wide adoption gave me the confidence to adopt it in my projects.

• If I use uv am I forcing others to use uv in order to use my project?

  No! Your project is still a fully PEP compliant project, meaning that it can be installed and run with standard Python tooling.

  
  

• Are there git hooks to ensure my requirements.txt and lock file are up to date?

  Yes, see this page.