Thanks pyenv + poetry, but I’ll use uv for Python virtualenvs now!

In 2022, Charlie Marsh released ruff, a powerful Python linter widely adopted by the Python community for its speed. He founded a company called Astral, recruited some people, and now released uv, an extremely fast and all-in-one Python package manager.

This is excellent news because Python virtual environments are generally hard to work with. There are a lot of tools, and they don’t manage the full workflow. This means that people usually learn about them at an advanced state of their Python journey, even though not using them is the highway to chaos.

To ease this workflow, our standard at Theodo Data&AI is to use pyenv to manage Python versions. We then combine it with poetry to manage dependencies and use either to manage virtual environments.

This article is here to show you why we shift and why you should too!

But it might still be a bit theoretical for you, so let’s see in detail both pyenv+poetry and uv workflow from scratch to project installation.

Workflow comparison

The pyenv + poetry workflow

You see that there are a lot of different operations, and the separation between 2 tools complicates a lot of things. There are also tricky cases such as the poetry install command, which does not delete packages if they are not needed anymore unless you add --sync.

Another point is that these commands change a bit depending on how you installed pyenv.

The new uv workflow

Some of these commands are not even necessary, because uv automatically installs necessary libraries and Python version when you run uv add or uv run!

As an example, you only need these commands to run a tiny FastAPI websockets demo (or any project actually!):

Look how much simpler it is! One important point is that all these commands are the same whether you use MacOS, Linux, or Windows, except for the installation command on Powershell but it happens only once.

Go speedy with uv!

Another great quality about uv is its speed compared to poetry!

Let’s take a very simple example by creating a new virtual environment in Python 3.12 and adding gradio, streamlit, and matplotlib as dependencies. This is done on an Intel MacBook Pro from 2019.

Poetry takes 17.3 seconds, during which 4.7 seconds are spent resolving dependencies.

Creating an equivalent virtual environment with uv is done in 7.9 seconds, with only 0.64ms spent on dependency resolution!

When in the past you could spend 1-2 minutes just for poetry to tell you that the dependencies are unsolvable, now you will know almost instantly!

How do I migrate from pyenv+poetry to uv?

Good news! It’s actually pretty easy because uv uses the standard pyproject.toml format, which is also used by other tools like PDM (thanks Sebastián Ramírez for the idea):

1. Go to your project folder
2. Delete the .python-version file if it exists;
3. Run uvx pdm import pyproject.toml (uvx is used to install command line tools, in the same way as pipx);
4. Update the new pyproject.toml by deleting poetry-related sections and renaming pdm-related sections (see the uv docs for pyproject.toml format);
5. Generate the .venv folder by running uv sync.

As you see, it’s very easy and shouldn’t take more than 5 minutes.

To update all code files (Makefile, CI/CD, Dockerfile, ...) which use poetry and/or pyenv commands, you can use the workflow Gist above or the uv docs to translate old commands to their uv version, which should also be very easy. For Dockerfiles, Astral provides a doc page of good practices here that are worth reading.

Conclusion

It’s impressive to see Astral hit just right two times in a row. Big thanks to poetry and pyenv for helping the Python community all these years, but uv is too good of a product and too easy to migrate, so I don’t see any reason not to use it if you’re a Python dev.

I focused here on project setup and migration, but you will also see speed improvements in everyday tasks such as Docker builds and CI/CD install stage, so this is an investment with short-term return.

If you want details on what makes uv so fast, I recommend watching this video of a talk done by Charlie Marsh himself.

If you are looking for professional guidance from data experts, don't hesitate to contact us!