django + uv

django-uv-setup.md

Django + uv Setup Cheat Sheet

A practical README.md / Gist for setting up Django with uv, including:

• Python version management
• Project initialization
• Installing / adding / removing packages
• Pinning package versions
• Updating dependencies
• Base uv commands

What is uv?

uv is Astral’s fast Python package and project manager. It replaces most uses of:

• pip
• venv
• virtualenv
• pip-tools
• pyenv (partially, for Python installs)

Install uv

macOS / Linux

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

Windows (PowerShell)

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

Verify:

uv --version

Python Version Management

Install a specific Python version

uv python install 3.12

Install an exact patch version:

uv python install 3.12.4

List installed Python versions:

uv python list

Create a Django Project

Initialize a new project

uv init --no-package --python 3.13 core

This creates:

core/
├── pyproject.toml
├── .python-version
├── README.md
└── src/

Pin the Python Version

Create or edit .python-version:

3.12

Or set it automatically:

uv python pin 3.12

This ensures everyone uses the same Python version.

Create and Activate the Virtual Environment (if not there)

Create the environment:

uv venv

Use a specific Python:

uv venv --python 3.12

Activate it:

Linux / macOS

source .venv/bin/activate

Windows

.venv\Scripts\activate

Install Django

Latest compatible version

uv add django

Install a specific major version

uv add "django>=5.2,<5.3"

Install an exact version

uv add django==5.2.5

This updates both:

• pyproject.toml
• uv.lock

Start the Django Project

uv run django-admin startproject config .

Run migrations:

uv run python manage.py migrate

Start the development server:

uv run python manage.py runserver

Base uv Commands

Initialize

uv init

Create venv

uv venv

Run a command inside the venv

uv run python manage.py runserver

Install / add a package

uv add requests

Remove a package

uv remove requests

Install development dependencies

uv add --dev pytest ruff black

Sync environment from lock file

uv sync

Upgrade all dependencies

uv lock --upgrade
uv sync

Package Version Control

Compatible release (~=)

uv add "django~=5.2"

Equivalent to:

>=5.2,<5.3

Exact pin

uv add django==5.2.5

Best for reproducible deployments.

Range pin

uv add "django>=5.2,<6.0"

Example pyproject.toml

[project]
name = "mysite"
version = "0.1.0"
requires-python = ">=3.12,<3.13"
dependencies = [
    "django==5.2.5",
    "psycopg[binary]==3.2.9",
]

[dependency-groups]
dev = [
    "pytest==8.4.1",
    "ruff==0.12.8",
    "black==25.1.0",
]

Important

requires-python = ">=3.12,<3.13"

This restricts the project to Python 3.12 only.

Install Additional Packages

Production dependency

uv add djangorestframework

Development-only dependency

uv add --dev ipython

Remove Packages

uv remove djangorestframework

Remove a dev dependency:

uv remove --dev ipython

Reproducible Installation

For a fresh clone:

git clone 
cd mysite

uv sync

uv sync will:

• create .venv
• install the correct Python dependencies
• use the exact versions from uv.lock

Upgrading Dependencies

Upgrade one package

uv add django@latest

Or:

uv add django==5.2.6

Upgrade everything

uv lock --upgrade
uv sync

Common Django Commands with uv

Create app

uv run python manage.py startapp blog

Make migrations

uv run python manage.py makemigrations

Apply migrations

uv run python manage.py migrate

Create superuser

uv run python manage.py createsuperuser

Open Django shell

uv run python manage.py shell

Recommended Versions (August 2026)

Why:

• Python 3.12 is mature and widely supported.
• Django 5.2 LTS receives long-term support and is the safest production choice.

Complete Quick Start

# install Python
uv python install 3.12

# create project
mkdir mysite
cd mysite

# initialize uv
uv init

# pin Python
uv python pin 3.12

# create virtual environment
uv venv

# install Django LTS
uv add "django~=5.2"

# create Django project
uv run django-admin startproject config .

# run migrations
uv run python manage.py migrate

# start server
uv run python manage.py runserver

Open:

http://127.0.0.1:8000

Useful Maintenance Commands

Minimal Production Template

uv init
uv python pin 3.12
uv venv

uv add "django==5.2.5"
uv add "gunicorn==23.0.0"
uv add "psycopg[binary]==3.2.9"

uv add --dev "ruff==0.12.8"
uv add --dev "pytest==8.4.1"

This gives you:

• locked Python version
• locked package versions
• reproducible installs
• separate dev dependencies
• fast installs via uv

TL;DR

# one-time setup
uv python install 3.12
uv init
uv python pin 3.12
uv venv

# dependencies
uv add "django~=5.2"
uv add --dev pytest ruff

# run Django
uv run python manage.py runserver

# update
uv lock --upgrade
uv sync

# remove
uv remove django

Best practice: commit these files to Git:

pyproject.toml
uv.lock
.python-version

That is the uv equivalent of requirements.txt + pyenv + virtualenv, but with faster installs and fully reproducible dependency management.

Export Dependencies to requirements.txt

uv can export the locked dependencies from uv.lock into a standard requirements.txt file for Docker, CI, or platforms that require pip-style requirements. The recommended approach is to export without development packages and hashes:

uv export --no-dev --no-hashes -o requirements.txt

For a Linux Docker environment, you can specify the platform to avoid unnecessary platform-specific packages:

uv export --no-dev --no-hashes --python-platform linux -o requirements.txt

Include development dependencies when needed:

uv export --no-hashes -o requirements.txt

uv export uses the versions from uv.lock, making the generated requirements.txt reproducible.