I carved out some time recently to start playing with the new Python package installer and resolver, uv.
uv makes big promises and claims to be 10-100x faster than pip and pip-tools. From my experiments over the last few weeks, it lives up to this promise.
I’m using it locally for my virtual environments, in my Dockerfiles to rebuild my containers, and for CI using GitHub Actions. Across the board, anything I do with pip or pip-tools is remarkably faster.
My average GitHub Actions CI workflows dropped from ~2 minutes to 50 seconds. This cuts the minutes I use in half and, in theory, my monthly bill in half.
My goal in sharing my configs is more “show” than “tell' because I will copy and paste these for weeks and months to come.
local development
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 so that I’m using 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 PATH /venv/bin:$PATH. # this is new
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
RUN python -m uv venv /venv # this is new
COPY requirements.txt /src/requirements.txt
RUN uv pip install --requirement /src/requirements.txt # this is updated
WORKDIR /src/
GitHub Actions
GitHub Actions are a little harder to explain, but my workflows started off 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
- name: Collect Static Assets
run: |
python -m manage collectstatic --noinput
main.yml after
The biggest pain point that I ran into along the way 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 uv
python -m uv venv .venv
echo "VIRTUAL_ENV=.venv" >> $GITHUB_ENV
echo "$PWD/.venv/bin" >> $GITHUB_PATH
python -m uv pip install --requirement requirements.in
- name: Collect Static Assets
run: |
. .venv/bin/activate
python -m manage collectstatic --noinput
Conclusion
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.
Updates
2024-03-08 - I modified the ENV PATH statement to prepend instead of replacing the value.
