How to Switch to uv: Replace pip, virtualenv, and Poetry in Your Python Project

Python package management has always been too complicated. To do it properly you needed pip to install packages, virtualenv or venv to isolate environments, pyenv to manage Python versions, and pip-tools to generate a proper lockfile. That's four separate tools, four different config formats, and four things that can break in CI.

uv fixes all of that. It's a single Rust binary from Astral (the same team that built ruff) that handles everything. Not "a little faster" fast: we're talking 10 to 100 times faster than pip on cold installs, and near-instant on warm ones.

This guide is specifically for migrating an existing project. If you're starting fresh, the workflow is even simpler, but most of us have a requirements.txt or pyproject.toml that needs to come along for the ride.

The table above covers the five commands you will type on day one. This one is the version worth keeping open in a browser tab for the first week, because it maps the whole surface area of pip, pip-tools, pyenv, pipx, and Poetry onto uv.

The pattern to internalise is that uv splits every operation into two halves: changing what your project declares (uv add, uv remove, uv lock) and making your environment match that declaration (uv sync, uv run). pip never had that split, which is exactly why pip install could quietly drift your environment away from your requirements file without anyone noticing until a deploy failed.

Two rows deserve a footnote. uvx is not a separate program you have to install: it ships inside the uv binary and is shorthand for uv tool run. It creates a throwaway, cached environment, runs the tool, and leaves nothing behind in your project, which is why it is the right way to run one-off formatters, scaffolders, and migration scripts.

uv tree is the command most people discover last and then use constantly. It prints the resolved dependency graph for your project, and uv tree --invert flips it so you can ask the question you actually care about during an upgrade fight: which of my direct dependencies is dragging in this old version of urllib3?

It is worth understanding where the speed comes from, because it changes how you use the tool. The gains are not one clever trick, they are four separate design decisions stacked on top of each other.

That last point has a practical consequence worth changing your habits over. Because a .venv is mostly links into the shared cache, deleting and recreating it is close to free. If an environment ever looks wrong, do not debug it: run rm -rf .venv && uv sync and move on. With pip that was a two minute penalty, so people learned to poke at broken environments instead of rebuilding them.

It also means ten projects that all depend on the same version of numpy store that wheel once on disk, not ten times. The tradeoff is that hardlinks only work when the cache and the virtual environment live on the same filesystem, which is why Docker builds sometimes need UV_LINK_MODE=copy (covered in the troubleshooting section below).

Pipenv projects migrate more cleanly than most people expect, because Pipfile and Pipfile.lock carry the same information uv needs. The same migrate-to-uv tool used for Poetry detects a Pipfile automatically:

If you would rather do it by hand (worth it when your Pipfile has unusual markers or VCS dependencies), Pipenv can print your dependencies in requirements format and uv can read that file directly:

Once uv.lock is generated and your tests pass, delete Pipfile, Pipfile.lock, and the two temporary requirements files. Keeping them around invites someone to run pipenv install six months from now and quietly build a second environment.

The one feature with no direct replacement is Pipenv's [scripts] section. uv is a package manager, not a task runner, and it does not read a scripts table from pyproject.toml. You have three reasonable options.

If you are coming from the JavaScript side and missing the ergonomics of a scripts block, the patterns in npm scripts you should know translate almost directly onto a Makefile wrapping uv run.

uv.lock is not a pip freeze dump with a different name, and the difference matters. A frozen requirements file records what happened to be installed on one machine, running one Python version, on one operating system. Regenerate it on a colleague's laptop and you get a different file.

uv.lock is a universal lockfile. uv resolves your dependency graph for every platform and every Python version allowed by your requires-python range, then records all of those resolutions in one file with environment markers attached. A Linux CI runner and an Apple Silicon laptop read the same lockfile and each install the correct wheels from it.

Every entry carries a hash, so an install is verified against the exact artifact that was resolved. If a package is ever yanked and republished with different contents, your install fails loudly instead of silently picking up different code.

The file is generated, so never hand-edit it. Change pyproject.toml, then re-lock. Note that uv add and uv remove update pyproject.toml, uv.lock, and your environment in a single command, so you rarely call uv lock directly outside of upgrades.

The distinction between --locked and --frozen trips people up, so it is worth stating plainly. --locked verifies that the lockfile still matches pyproject.toml and errors if it does not. --frozen skips that check entirely and installs whatever the lockfile says. Use --locked in CI, where you want a forgotten uv lock to fail the pull request, and --frozen in a Docker build, where you may not even copy pyproject.toml into the layer.

If something outside your project still expects a requirements.txt (an old deployment script, a security scanner, a platform that only understands pip), uv can generate one from the lockfile without giving up the lockfile as the source of truth:

pyenv compiles CPython from source. That means you need a C compiler, the right development headers for OpenSSL, readline, zlib, and libffi, and roughly two to five minutes per version. When a build fails, the error is usually a missing system library, three layers deep in a make log.

uv skips all of that. It downloads prebuilt standalone CPython distributions, so installing an interpreter is a download and an extract, typically a few seconds. Nothing is compiled, nothing touches your system Python, and the interpreters live in uv's own directory rather than being wired into your shell through a shim.

There are two version declarations in a uv project and they answer different questions. .python-version says which interpreter this working copy should use right now. requires-python in pyproject.toml says which Python versions your code supports, and it constrains the resolver: set requires-python = ">=3.11" and uv will refuse to lock a dependency that dropped 3.11 support.

Libraries should set a range in requires-python and test the edges. Applications can be stricter, because you control the deployment target. Either way, commit .python-version so nobody on the team is silently running a different interpreter, and so uv python install with no arguments in CI knows what to fetch.

Most uv migrations are uneventful. These are the five failures that account for nearly all of the ones that are not.

This is the most common shock for teams coming from pip, and it is not a uv bug. pip installs sequentially and lets a later package overwrite an earlier one's dependency, so a genuinely impossible requirement set can appear to install fine and then break at runtime. uv resolves the whole graph up front, so it tells you at install time.

uv's error output names the specific conflicting requirements and the packages that introduced them. Read it before changing anything: it usually points straight at one over-tight pin. Then work through the options in order:

Internal package servers (Artifactory, Nexus, CodeArtifact, a private PyPI mirror) are configured in pyproject.toml rather than in a global pip config, which means the configuration is version controlled and every developer gets it automatically.

Setting explicit = true is the security-conscious choice. It means uv only looks at that index for packages explicitly routed to it under [tool.uv.sources], and everything else comes from PyPI. Without it, an index that serves an unexpected package name can shadow a public one, which is the shape of a dependency confusion attack.

Keep credentials out of the URL. uv reads them from environment variables named after the index, so an index named internal uses UV_INDEX_INTERNAL_USERNAME and UV_INDEX_INTERNAL_PASSWORD. In CI those come from your secrets store, and locally they can live in your shell profile or a credential helper.

pip install -e . has a direct equivalent, and in a uv project you usually do not need it at all: uv sync installs your own package in editable mode by default. Where it matters is a sibling library you are developing alongside the application.

That records a path source in pyproject.toml, so imports resolve to your working copy and edits take effect without reinstalling. The catch is that a path source is machine-specific: it will not work for anyone who does not have that directory checked out at the same relative location.

For anything more than a quick experiment, convert the setup into a workspace instead. Workspace members are declared once at the repository root, share a single lockfile, and work identically for every developer and in CI.

If you install something with uv pip install and then run uv sync, it disappears. That is correct behaviour, not a bug. uv sync makes the environment match the lockfile exactly, and anything not declared in pyproject.toml is by definition not in the lockfile.

The fix is to stop mixing interfaces. uv pip install exists as a compatibility shim for scripts and workflows that have not migrated yet; in a project with a uv.lock, use uv add. If you only want a package for a single command and not permanently, use the --with flag instead of installing anything:

A warning about failing to hardlink files means the uv cache and the target environment are on different filesystems. This happens inside Docker with a cache mount, on some CI runners, and when a project lives on a network share or a mounted volume.

It is a performance warning rather than an error, and the fix is one environment variable: UV_LINK_MODE=copy. Set it in your Dockerfile or CI environment. You can also relocate the cache next to the environment with UV_CACHE_DIR so hardlinking works again, which is usually the faster option on a build machine you control.

Honest limitations, because every migration guide that claims none is hiding something.

For everything else, the migration is genuinely a couple of hours for a typical service and the payback is immediate: faster CI, faster Docker builds, one tool instead of four, and a lockfile that means the same thing on every machine. Once uv is in place, the rest of your Python tooling gets easier to modernise too, whether that is adopting ruff or moving onto newer language features like the ones in t-strings.