Skip to content

uv

We will be using the uv tool in this course for managing Python environments.

This means we will be able to use it in lieu of tools such as: virtualenv, pip, conda, pyenv, poetry, and pdm. If you've worked in Python before, this hopefully comes as a relief.

Whether you've used Python before or not, this page should provide what you need to know about uv in this class. After reading this you may decide to dive deeper with the uv docs.

Note

If you are using the provided server environment uv is already installed.

If you are developing locally please see Developing Locally first.

Using uv

For this course, every assignment will come with uv configuration files (e.g. pyproject.toml and uv.lock).

These files specify any dependencies (third-party tools and libraries) that our given project depends upon.

By having these files exist on a per-project basis, different projects can use different tools (and versions of tools), and we do not need to worry about incompatabilities between say, the version of Pandas used in a PA for this course and for a project you're using at work.

(Behind the scenes, uv is managing a virtual environment for you, replacing virtualenv, pip, poetry, and pdm if you are familiar with those tools.)

uv sync

After checking out a project, this is the first command you should run.

It will install all necessary packages into a local environment specific to that project.

For example:

course/$ git clone git@github.com:jamesturk/assignment1.git
course/$ cd assignment1
course/assignment1/$ uv sync
Resolved 24 packages in 0.97ms
Audited 14 packages in 0.11ms

uv run <command>

To run commands using the installed dependencies, you must:

  1. Be inside the assignment directory where uv sync was previously run.
  2. Prefix those commands with uv run

So pytest becomes uv run pytest. Some common commands:

  • uv run pytest - Run tests.
  • uv run python file.py - Execute a specified python file.
  • uv run ipython - Run an interactive REPL with access to all dependencies.

uv add / uv remove

These commands add and remove dependencies, they will both update your pyproject.toml, uv.lock, and local environment.

If you see a library that gives an instruction like: pip install Django

You would instead write: uv add Django

For the most part you will not need to use this, but in later assignments where you are given the option to use different libraries, you might. Be sure to commit the changes to pyproject.toml and uv.lock!

uv remove will do the opposite: the equivalent of pip uninstall or poetry add, etc.

Why uv?

It has been said that the hardest part of working with Python is managing third party tools, and uv is an attempt to address that.

I chose it because it offers three distinct advantages:

  • It uses Python-standard conventions, such as installing packages from PyPI and using a pyproject.toml file.1
  • It allows installing Python, python packages, and eases developing locally with a single tool.2
  • It is, as of 2024, quickly gaining mindshare. Many experienced Python developers have publicly made the switch in recent months.3

Of course, introducing a new tool comes with some risks:

It may still have unforeseen rough edges. I do not think given our limited use cases we are likely to run into them. I have tested uv thoroughly on my own projects and have had conversations with teams that are already using it in production, and I am confident that any issues we run into we can resolve.

You may find that a future class or employer is using an older tool. Unfortunately, this is already a major problem. Right now there are four common ways to manage environments in Python:

  • virtualenv and pip
  • conda
  • poetry
  • pdm

Not to mention pyenv and pipx which are often necessary in tandem with the above.

So a choice will always potentially be unique to this class. I think that it is worth choosing uv in light of the aforementioned advantages, especially the ease of use and rate of recent adoption.

XKCD #927

  1. Conda quite notably does not follow Python conventions, often leading to incompatibilities with other Python tools. It is also starting to monetize. ↩

  2. In the past, a combination of pyenv, pipx, poetry, and/or pdm was required to get the same functionality. ↩

  3. See https://simonwillison.net/2024/Aug/20/uv-unified-python-packaging/ and https://andrich.me/2024/09/uv-i-am-somewhat-sold/ for more. ↩