Skip to content

pip to uv: a command cheatsheet

by Tim Hopper
uv

A quick-reference table for developers switching from pip, venv, pyenv, pip-tools, or pipx to uv. Each section maps an old command to its uv equivalent.

Install uv first if you haven’t already.

Installing packages

Before (pip) After (uv)
pip install requests uv add requests
pip install requests==2.32.0 uv add "requests==2.32.0"
pip install "requests[socks]" uv add "requests[socks]"
pip install -r requirements.txt uv add -r requirements.txt
pip install -e . uv sync

uv add writes the dependency to pyproject.toml, locks it in uv.lock, and installs it in one step. There is no need to maintain a separate requirements file.

For an existing project that already has a pyproject.toml and uv.lock, use uv sync to install everything from the lockfile. This is the equivalent of pip install -r requirements.txt in a locked project.

Removing and inspecting packages

Before (pip) After (uv)
pip uninstall requests uv remove requests
pip list uv pip list
pip show requests uv pip show requests
pip check uv pip check
pip freeze uv pip freeze

uv remove updates pyproject.toml and uv.lock at the same time. The uv pip subcommands work against the active virtual environment the same way pip does.

Upgrading packages

Before (pip) After (uv)
pip install --upgrade requests uv lock --upgrade-package requests && uv sync
pip install --upgrade pip uv self update

To upgrade a single dependency, uv lock --upgrade-package requests re-resolves that package to the latest allowed version and rewrites uv.lock. Follow it with uv sync to install the result. To upgrade all dependencies at once, run uv lock --upgrade && uv sync.

Development dependencies

Before (pip) After (uv)
pip install -r requirements-dev.txt uv add --dev pytest ruff
(no built-in equivalent) uv sync --no-dev

uv tracks development dependencies in pyproject.toml under [dependency-groups]. Production installs that skip dev dependencies use uv sync --no-dev.

Virtual environments

Before (venv / virtualenv) After (uv)
python -m venv .venv uv venv
source .venv/bin/activate (not needed)
deactivate (not needed)
python script.py uv run script.py
python -m pytest uv run pytest

uv run executes a command inside the project’s virtual environment without requiring activation. If no virtual environment exists, uv run creates one automatically. This removes the most common source of “wrong Python” bugs.

Tip

Shell activation still works if you prefer it. Run uv venv to create the environment and activate it the usual way. But uv run is the recommended workflow because it guarantees the environment is in sync with uv.lock before every command.

Locking and compiling dependencies

Before (pip-tools) After (uv)
pip-compile requirements.in uv pip compile requirements.in
pip-compile --upgrade uv pip compile --upgrade requirements.in
pip-sync requirements.txt uv pip sync requirements.txt

These commands are useful for projects that still use the requirements.in/requirements.txt workflow. For new projects, the native uv workflow with pyproject.toml and uv.lock replaces pip-tools entirely.

Exporting to requirements.txt

uv command Result
uv export --format requirements-txt Print locked dependencies as requirements.txt to stdout
uv export --format requirements-txt > requirements.txt Write to a file
uv export --format requirements-txt --no-dev Exclude dev dependencies

Use uv export when a downstream tool or deployment process requires a requirements.txt file. The output comes from uv.lock, so versions are fully pinned.

Python version management

Before (pyenv) After (uv)
pyenv install 3.13 uv python install 3.13
pyenv local 3.13 uv python pin 3.13
pyenv versions uv python list
pyenv global 3.13 uv python install 3.13 --default

uv python pin writes a .python-version file, and uv automatically downloads the requested version if it isn’t already installed. This replaces pyenv for most workflows. See how to switch from pyenv to uv.

Running CLI tools

Before (pipx) After (uv)
pipx install ruff uv tool install ruff
pipx run ruff check . uvx ruff check .
pipx upgrade ruff uv tool upgrade ruff
pipx uninstall ruff uv tool uninstall ruff
pipx list uv tool list

uv tool install and uvx isolate each tool in its own virtual environment, just like pipx. uvx runs a tool without installing it permanently. See the uvx reference.

Starting a new project

Before After (uv)
mkdir myproject && cd myproject && python -m venv .venv uv init myproject && cd myproject

uv init creates a pyproject.toml, a .python-version file, and a virtual environment in one step. See Create your first Python project for a full walkthrough.

Running scripts with inline dependencies

No pip equivalent exists for this. uv supports PEP 723 inline script metadata:

plot.py
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "matplotlib",
# ]
# ///
import matplotlib.pyplot as plt

plt.plot([1, 2, 3], [1, 4, 9])
plt.savefig("plot.png")
uv run plot.py

uv reads the dependencies from the script header, creates a temporary environment, and runs the script. No pyproject.toml or virtual environment setup is needed.

Learn More

Last updated on
How to write self-contained Python scripts using PEP 723 inline metadata

Please submit corrections and feedback...