Python management with uv

Overview

Package dependencies/conflicts can be a pain, which you've probably learned if you've ever tried to continually add packages to a project/env via pip.

Our preferred solution for dealing with conflicting dependencies, adding new packages to an environment, and bumping versions mainly consists of:

1. listing our required packages in a requirements.in
2. compiling them to a requirements.txt via pip-tools or uv
3. creating a virtual environment and installing packages using requirements.txt

Note

All command line examples here are for a bash terminal. On a DCP laptop, the easiest way to get bash is to install git.

Install

uv can be installed with a standalone installer or a package manager (see full docs here):

• macOS and Linux

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

• Windows (new DCP laptops)

  winget install --id=astral-sh.uv  -e

• Windows (old DCP desktop PCs)

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Manage python versions

Warning

Without installing uv-managed python interpreters, uv will use any interpreters it can find on the machine to create virtual environments. This may cause issues, especially on Windows, and disrupts the isolated/self-contained approach of uv.

Python version 3.13 is used as the example version, these instructions are applicable to any version.

uv python list
uv python install 3.13

If prompted by uv, run uv tool update-shell to ensure the PATH includes necessary files.

Virtual environment

Create a virtual environment

uv venv --python 3.13

Activate the virtual environment before running any more uv commands

• macOS and Linux

  source .venv/bin/activate

• Windows

  .venv\Scripts\activate

List and install packages

Create your requirements.in in the root of your project

pandas
torch

Compile the requirements.txt file

uv pip compile requirements.in --output-file requirements.txt

Result should be something like this

# This file was autogenerated by uv via the following command:
#    uv pip compile requirements.in
filelock==3.18.0
    # via torch
fsspec==2025.5.1
    # via torch
jinja2==3.1.6
    # via torch
markupsafe==3.0.2
    # via jinja2
mpmath==1.3.0
    # via sympy
networkx==3.5
    # via torch
numpy==2.3.1
    # via pandas
pandas==2.3.0
    # via -r requirements.in
python-dateutil==2.9.0.post0
    # via pandas
pytz==2025.2
    # via pandas
six==1.17.0
    # via python-dateutil
sympy==1.14.0
    # via torch
torch==2.2.2
    # via -r requirements.in
typing-extensions==4.14.0
    # via torch
tzdata==2025.2
    # via pandas

Install your packages!

uv pip sync requirements.txt

You should be good to go! Just remember to activate the venv if you open up a new terminal.

Do check in your requirements.in and requirements.txt in git. Don't check in your virtual env! Make sure that the folder it's in is .gitignored.

Extra

Confirm the active python environment and its packages

which python
uv pip list

Use the --upgrade flag to upgrade compiled package versions in requirements.txt (or delete the file and run without the flag).

uv pip compile --upgrade requirements.in --output-file requirements.txt