How to migrate from requirements.txt to pyproject.toml with uv
uv can import dependencies directly from requirements.txt files, so switching to pyproject.toml takes only a few commands. Install uv first if you haven’t already.
Steps
1. Create a pyproject.toml file
$ uv init --bare
This creates a minimal pyproject.toml without sample code. If the project already has a pyproject.toml (from a tool like setuptools), skip this step.
2. Import your existing requirements
$ uv add -r requirements.txt
This command:
- Reads dependencies from requirements.txt
- Adds them to pyproject.toml
- Creates a lockfile (
uv.lock) that pins exact versions for reproducible installs - Installs dependencies in the project’s virtual environment
Tip
If requirements.txt contains pinned versions like requests==2.31.0, uv adds the package name without the pin. The exact resolved version is captured in uv.lock instead, which is the recommended approach for reproducibility.
3. Import development requirements
If you have a separate requirements-dev.txt (or requirements-test.txt, etc.):
$ uv add --dev -r requirements-dev.txt
This adds them as development dependencies, which are installed during development but excluded from production builds.
Verify that all dependencies were imported correctly:
$ uv pip freeze
4. Remove the old requirements files
Once you’ve confirmed the migration, remove the old files:
$ rm requirements.txt requirements-dev.txt
5. Manage dependencies with uv going forward
# Add new runtime dependency
$ uv add requests
# Add development dependency
$ uv add --dev pytest
# Remove dependency
$ uv remove requests
# Install all dependencies from lockfile
$ uv sync
Related
- Why choose pyproject.toml over requirements.txt? explains the benefits of switching
- Create your first Python project walks through starting a new uv project from scratch
- What is a lock file? covers how
uv.lockensures reproducible installs - What are Optional Dependencies and Dependency Groups? explains how dev dependencies work in pyproject.toml
- uv reference documents all uv commands
Also Mentioned In
- uv: A Complete Guide to Python's Fastest Package Manager
- pyproject.toml: Python Project Configuration File
- uv: Python Package and Project Manager
- Which Python package manager should I use?
- Why Should I Choose pyproject.toml over requirements.txt for managing dependencies?
- Why use native uv commands instead of uv pip
- Why You Should Try uv if You Use Python
Get Python tooling updates
Subscribe to the newsletter