How to migrate a Django project from pip-tools to uv

1. Read the include chain

Open each .in file and note which layer it pulls in:

$ head -1 requirements/*.in
==> requirements/base.in <==
django>=5.0,<5.2

==> requirements/dev.in <==
-r base.txt

==> requirements/test.in <==
-r base.txt

PS> Get-ChildItem requirements\*.in | ForEach-Object { "==> $($_.Name) <=="; Get-Content $_ -TotalCount 1 }
==> base.in <==
django>=5.0,<5.2
==> dev.in <==
-r base.txt
==> test.in <==
-r base.txt

Each layer maps to one destination:

Import the .in files, never the .txt files. A compiled base.txt lists every transitive dependencyA package your dependency depends on. When you install requests, its own dependencies (urllib3, certifi, etc.) are transitive dependencies. at an exact version, so importing it writes packages into pyproject.toml that Django never asked for directly.

2. Create pyproject.toml beside manage.py

$ uv init --bare --python 3.13
Initialized project `mysite`

--bare writes a pyproject.toml with no sample code, no README, and no [build-system] table, which is what a Django site wants. Your manage.py and settings package stay where they are.

3. Pin the interpreter pip-compile used

Use the Python version your production environment runs in both commands; this example uses 3.13. The initialization command sets requires-python; pin the development interpreter explicitly:

$ uv python pin 3.13
Pinned `.python-version` to `3.13`

The pin selects the development interpreter. uv resolves the lockfile across the Python range declared by requires-python; importing .in files can select different versions from the old compiled files even when the interpreter matches production.

4. Import the base layer

$ uv add -r requirements/base.in
Using CPython 3.13.14
Creating virtual environment at: .venv
Resolved 8 packages in 132ms
Installed 6 packages in 182ms
 + asgiref==3.12.1
 + django==5.1.15
 + django-environ==0.14.0
 + psycopg==3.3.4
 + psycopg-binary==3.3.4
 + sqlparse==0.6.0

uv preserves the constraints base.in declares and adds a lower bound for the rest:

[project]
dependencies = [
    "django>=5.0,<5.2",
    "django-environ>=0.14.0",
    "psycopg[binary]>=3.3.4",
]

Exact versions go to the lockfileA file that records the exact version of every installed package, so everyone working on the project gets identical installs. (uv.lock) instead, so pyproject.toml keeps declaring intent while the lockfile handles reproducibility.

5. Import each layer without its include line

dev = [
    "asgiref==3.12.1",
    "django==5.1.15",
    "django-debug-toolbar>=6.3.0",
    "django-environ==0.14.0",
    "psycopg==3.3.4",
    "psycopg-binary==3.3.4",
    "ruff>=0.16.5",
    "sqlparse==0.6.0",
]

Pass only the lines each layer declares for itself:

$ uv add --group dev $(grep -v '^-r ' requirements/dev.in)
$ uv add --group test $(grep -v '^-r ' requirements/test.in)

PS> $devPkgs = Get-Content requirements\dev.in | Where-Object { $_ -notmatch '^-r ' }
PS> uv add --group dev $devPkgs

PS> $testPkgs = Get-Content requirements\test.in | Where-Object { $_ -notmatch '^-r ' }
PS> uv add --group test $testPkgs

Filtering out the -r line hands uv only the remaining package names. Verify the result before moving on:

[dependency-groups]
dev = [
    "django-debug-toolbar>=6.3.0",
    "ruff>=0.16.5",
]
test = [
    "pytest>=9.1.1",
    "pytest-django>=4.14.0",
]

6. Rebuild the layering with include-group

Dependency groups compose through the include-group key, defined by PEP 735, the standard for [dependency-groups] in pyproject.toml. If dev.in pulled in test.in under pip-tools, say so:

[dependency-groups]
dev = [
    {include-group = "test"},
    "django-debug-toolbar>=6.3.0",
    "ruff>=0.16.5",
]

No group needs to include the base layer. [project.dependencies] installs alongside every group, which is what the -r base.txt line was doing by hand.

uv sync installs the dev group by default, so one command now covers what pip-sync requirements/dev.txt did:

$ uv sync
Resolved 17 packages in 16ms

7. Run management commands through uv

uv run executes the command inside the project’s virtual environment, ensuring all dependencies are installed first. No activation step, and no stale environment:

$ uv run python manage.py check
System check identified no issues (0 silenced).

Apply the same prefix to migrate, runserver, and createsuperuser. Update the project README and any Makefile targets in the same commit so nobody keeps calling the old venv.

8. Retire pip-compile

Confirm production installs cleanly with groups excluded, which is the new pip-sync requirements/base.txt:

$ uv sync --no-default-groups
Resolved 17 packages in 2ms
Uninstalled 8 packages in 21ms
 - django-debug-toolbar==6.3.0
 - iniconfig==2.3.0
 - packaging==26.3
 - pluggy==1.6.0
 - pygments==2.21.0
 - pytest==9.1.1
 - pytest-django==4.14.0
 - ruff==0.16.5

Then delete requirements/ and the pip-compile invocations that wrote files into it:

$ rm -r requirements/

PS> Remove-Item -Recurse requirements

If a deployment target still reads a flat file, regenerate one from the lockfile instead of hand-maintaining it:

$ uv export --no-default-groups --format requirements-txt -o requirements.txt

The export carries hashes without extra flags and marks platform-specific packages with environment markers such as psycopg-binary==3.3.4 ; implementation_name != 'pypy'. The installer selects entries for its environment. See how to export requirements.txt from a uv project for group selection and project exclusion.

Add a drift check to CI so the lockfile cannot fall behind pyproject.toml:

$ uv lock --check