Skip to content

uv

Configuring your laptop for running code locally is an essential step in your growth as a developer.

In this course we will use uv to maintain a local Python installation.

This page should provide what you need to know about uv in this class.

Not Compatible with Conda

If you have already installed Python via conda/miniconda, you may need to uninstall it to get some things to work properly.

While most Python tools are mostly compatible, Conda does not follow the standards that these tools have adopted.

You are free to try to proceed without uninstalling, but if you run into issues see Paul Romer's Escaping from Anaconda on why and how.

Windows Users

If you are a Windows user, we strongly recommend using WSL to have a Linux environment on your machine.

TAs and I are used to working in a Unix-like environment as provided by MacOS, Linux, or WSL on Windows. Many commands that work on all three of these will not work in Windows Powershell.

Due to the vast number of possible configurations, course staff are not able to offer technical support for Windows-specific issues and can only offer limited support for machine-specific issues regardless of platform.

Installing uv and python

  1. Follow the instructions on this page, for your environment: installing uv.

  2. Once uv is installed, type uv python install 3.13 in your terminal.

  3. After Python is installed, verify the version with uv run python -V. You should see a version that starts with 3.13.

If you have any trouble with this step please post on Ed asking for help.

Python 3.13 will be the version of Python used for this course.

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.

After reading this you may decide to dive deeper with the uv docs.

Why uv?

uv is a newer tool, if you have used Python before you may wonder why we're adopting it.

Compared with older tools, it offers some 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 signficantly faster than most alternatives.
  • It has quickly become a favored tool among long-time Python developers.3

Of course, you will need to use other tools in other classes, but that is par for the course in our field.

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

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