Last month, I wrote Python’s UV tool is actually pretty good about Astral’s new Python package installer and resolver uv, and this is a follow-up post.

Since last month, I have added uv to over a dozen projects, and I recently learned that you could skip the venv step for projects that use containers or CI where the environment is already isolated.

I mistakenly thought uv required a virtual environment (aka venv), but Josh Thomas recently pointed out that it’s unnecessary.

The trick is to pass the --system option, and uv will perform a system-wide install. Here’s an example:

uv pip install --system --requirement requirement.txt

Now that I have seen this, I wish pip also used this approach to avoid developers accidentally installing third-party packages globally.

local development

Nothing has changed with my justfile example from last month.

When I’m working with containers, I create a virtual environment (venv) because I will need most of my project requirements installed outside of the container so that my text editor and LSP can resolve dependencies. uv’s default behavior of respecting a venv is all we need here.

Every one of my projects has a justfile (it’s like Make but works the same everywhere) with “bootstrap” and “lock” recipes. My “bootstrap” recipe installs everything I need to work with the project locally. I use my “lock” recipe to lock my requirements.txt file to use the exact requirements locally and in production.

justfile before

My justfile might look like this:

@bootstrap
    python -m pip install --upgrade pip
    python -m pip install --upgrade --requirement requirements.in
    
@lock *ARGS:
    python -m piptools compile {{ ARGS }} ./requirements.in \
        --resolver=backtracking \
        --output-file requirements.txt

justfile after

For the most part, uv shares most of the same syntax as pip so you can start by changing your pip references to uv pip:

@bootstrap
    python -m pip install --upgrade pip uv
    python -m uv pip install --upgrade --requirement requirements.in
    
@lock *ARGS:
    python -m uv pip compile {{ ARGS }} requirements.in \
        --resolver=backtracking \
        --output-file requirements.txt

Dockerfiles

Everyone’s container setup is going to be different, but I use Docker and Orbstack, which use a Dockerfile.

Dockerfile before

FROM python:3.12-slim-bookworm

ENV PIP_DISABLE_PIP_VERSION_CHECK 1
ENV PYTHONDONTWRITEBYTECODE 1
ENV PYTHONPATH /srv
ENV PYTHONUNBUFFERED 1

RUN apt-get update

RUN pip install --upgrade pip

COPY requirements.txt /src/requirements.txt

RUN pip install --requirement /src/requirements.txt

WORKDIR /src/

Dockerfile after

FROM python:3.12-slim-bookworm

ENV PIP_DISABLE_PIP_VERSION_CHECK 1
ENV PYTHONDONTWRITEBYTECODE 1
ENV PYTHONPATH /srv
ENV PYTHONUNBUFFERED 1

RUN apt-get update

RUN pip install --upgrade pip uv  # this is updated

COPY requirements.txt /src/requirements.txt

RUN uv pip install --system --requirement /src/requirements.txt  # this is updated

WORKDIR /src/

GitHub Actions

GitHub Actions are a little more complicated to explain, but my workflows started similar to this before I made the switch to uv:

main.yml before

  - name: Set up Python 3.12
    uses: actions/setup-python@v5
    with:
      python-version: '3.12'

  - name: Install dependencies
    run: |
            python -m pip install --requirement requirements.in

main.yml after

The most significant pain point I ran into was related to GitHub Issue #1386, which has a useable workaround.

  - name: Set up Python 3.12
    uses: actions/setup-python@v5
    with:
      python-version: '3.12'

  - name: Install dependencies
    run: |
      python -m pip install --upgrade uv  # this is new
      python -m uv pip install --system --requirement requirements.in  # this is updated

Gotchas

The only gotchas I have encountered with uv is when I’m trying to install a Python package from a remote zip file.

Previously, I could copy and paste the GitHub repo URL, but uv required we use the format package-name @ url-to-zip-file

requirements.in before

# requirements.in
https://github.com/jefftriplett/django-feedreader/archive/main.zip

requirements.in after

# requirements.in
django-feedreader @ https://github.com/jefftriplett/django-feedreader/archive/main.zip

Conclusion

This update helps remove a few steps from updating your projects, and it should shave a few minutes off of updating projects to use it.

I hope this was helpful to anyone who is considering making the switch to uv. I love to hear about how much time it saves you.