An ode to uv

Kenny Chou · January 16, 2025

Python   Tutorials   uv

After using uv for a couple months, it continues to impress. It’s fast. It’s easy to use. I have not completely abandoned Poetry because my existing projects are already configered to use Poetry, and my colleagues have not yet adopted uv. Nonetheless, uv still offers tremendous advantages in my workflow. This post will explain how I make use of uv in my workflows and its advnatages over other tools, when my projects are still configured for Poetry.

Installation

First, install uv. There are many ways to install uv. I prefer to use one of these methods:

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

# pipx
pipx install uv

# brew
brew install uv

Advanced settings for linux servers

If you’re working on linux servers, you may have do adjust some settings due to the limited amount of disk space available in the home directory.

Add the following to your .bashrc

export UV_PYTHON_INSTALL_DIR=my_python_install_dir

See additional settings for uv in the docs.

By default, uv will also utilize your ~/.cache directory. So I recommend creating a symlink to a directory that’s not space-restricted.

ln -s my_unrestricted_dir/.cache ~/.cache

! If you run into invalid peer certificate: UnknownIssuer solution issues, run export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt in console then try again. (source)

Python Management

uv replaces pyenv

You don’t have to explicitly install python versions, since uv will download any missing python versions for you. But sometimes, it’s good to be explicit.

# Install one or more python versions
uv python install 3.11 3.12

# View python installations
uv python list

Python binaries managed by uv lives in a specific directory. You can control where Python interpreters are installed using the UV_PYTHON_INSTALL_DIR environment variable. See other fine-grained control you have in the docs.

Environment management

uv replaces virtualenv

# explicitly set up an environment.
uv venv <path/myenv> --python 3.11

source <path/myenv>/bin/activate

Why use uv for environment management? Primarily because it can also act as a Python version manager. It quickly downloads python interpreters if they aren’t found on your system. I’ve compared uv with other common environment managers here.

Important parameters

  • --python <version> – uses the specified python version
  • --seed – uv’s virtual environments don’t have pip, setuptools or wheels by default. The --seed option makes them available.

See the complete list of parameters here.

Package Installation

uv replaces pip

uv is much faster than pip and poetry. Can we use it to install a Poetry-managed project? Absolutely, yes!

In my workflow, I generate requirement.txt files because it doesn’t make sense to include poetry in production. This is done automatically with poetry-auto-export. With poetry-auto-export installed, new requirement files are generated every time poetry.lock file is updated.

Since uv is a drop-in replacement for pip, we can call

# install your dependencies
uv pip install -r requirements.txt

# install the current project
uv pip install . --no-deps

If you don’t have poetry-auto-export, you can manually export the requirement files (or write a script that does it for you).

In situations where you have to install packages over and over again, uv can significantly speed up your workflow. Such as…

  • Running tests with nox/tox. In these situations, packages are installed in fresh environments, which are destroyed after the test finishes.
  • During CI workflows – see Using uv in Github Actions. Use uv to install both Python and your requirements!

Update: May 2025

If your projects have been configured for Poetry versions 2.x and higher and your dependencies are specified in the [project] table of your pyproject.toml, then you can directly call uv sync to install your dependencies.

System-wide tool management

uv replaces pipx

pipx install tools like Poetry and Nox in isolated envionments to ensure their dependencies are not in conflict with other system-level tools’ dependencies. uv has its own tool management system. To install a tool in an isolated environment, run:

uv tool install <package>

The tools will be installed in the UV_TOOL_DIR, which by default is ~/.local/share/uv/tools.

Like pipx, uv will also add any installed tools onto your PATH, making it available to other programs on your system.

you can upgrade and uninstall tools via

uv tool upgrade <package>
uv tool uninstall <package>

However, uv’s strength comes from being able to run these tools without explicitly installing them.

# directly run a package; uv installs it if unavailable. The tool will be uninstalled after the command is completed.
uv tool run <package>

# or use the shorthand
uvx <package>

It is up to you to decide which is more appropriate – installing the tool, or simply executing the tool.

Tools with python dependencies

Here’s an interesting scenario – your system has python 3.7 installed (python --version returns 3.7). You want to install Poetry verion 2.x, which requires python 3.10. What do you do? In this scenario, we can install the desired Poetry version via:

uv tool install poetry --python 3.10

uv implicitly installs python 3.10 in the background, creates a virtual environment with python 3.10, then installs Poetry using that environment.

poetry --version should now return 2.1.3

See the Tools documentation for more details.

Summary

These are by no means the full extent of uv’s capabilities. It handles monorepos much better than Poetry via workspaces. It can manage entire projects, build and publish packages. I haven’t yet used uv for these tasks, but I’ll update this post once I do.

Further reading