uv Cheat Sheet (for this project)

Coming from venv + pip? uv replaces both — it manages the virtualenv and installs packages. You rarely activate the venv manually; uv run <cmd> runs a command inside the project's .venv automatically.

Mental model: venv/pip → uv

You used to…	With uv
python -m venv .venv	uv venv (or automatic on sync)
source .venv/bin/activate	not needed — use uv run …
pip install -r requirements.txt	uv sync
pip install <pkg>	uv add <pkg>
pip uninstall <pkg>	uv remove <pkg>
pip install -U <pkg>	uv lock --upgrade-package <pkg>
pip freeze > requirements.txt	uv export --no-hashes -o requirements.txt
python manage.py <cmd>	uv run python manage.py <cmd>
python script.py	uv run python script.py

Basics

uv sync                     # create .venv + install everything from uv.lock
uv sync --upgrade           # re-resolve and upgrade deps within pyproject bounds
uv add django-extensions    # add a dependency (updates pyproject.toml + uv.lock)
uv add --dev pytest         # add a dev-only dependency
uv remove django-extensions # remove a dependency
uv lock                     # regenerate uv.lock from pyproject.toml
uv tree                     # show the dependency tree
uv pip list                 # list installed packages in the env
uv python pin 3.12          # pin the Python version (writes .python-version)

Django management (this project)

Run any manage.py command by prefixing with uv run:

uv run python manage.py runserver          # dev server → http://localhost:8000
uv run python manage.py shell              # interactive Django shell
uv run python manage.py makemigrations     # create migration files from model changes
uv run python manage.py migrate            # apply migrations to the database
uv run python manage.py showmigrations     # list migrations + applied state
uv run python manage.py createsuperuser    # create an admin user
uv run python manage.py collectstatic      # gather static files → staticfiles/
uv run python manage.py test               # run the test suite
uv run python manage.py check              # system checks
uv run python manage.py dbshell            # open the database shell

Tip: uv run manage.py <cmd> (without python) also works.

Activating the venv (if you prefer the old way)

uv run is recommended, but you can still activate the venv like before:

source .venv/bin/activate
python manage.py runserver     # now plain python works
deactivate

Advanced

uv run --with ipython python manage.py shell   # run with an extra package, no install
uv sync --frozen                               # install exactly from uv.lock, never re-resolve (CI)
uv sync --no-dev                               # production install, skip dev deps
uv export --no-hashes -o requirements.txt      # regenerate requirements.txt from the lock
uv cache clean                                 # clear uv's global download cache
uv self update                                 # update uv itself

Rules of thumb

• Commit pyproject.toml and uv.lock; never commit .venv/.
• After pulling changes that touch pyproject.toml/uv.lock, run uv sync.
• Add packages with uv add, not pip install — so the lockfile stays accurate.