uv is Astral's Python package and project manager, written in Rust. It combines Python installation, project environments, dependency locking, standalone scripts and command-line tools. Choose it when consolidating those jobs solves a problem in your workflow. Teams that require existing Rye or Hatch task aliases unchanged should keep that requirement central: issue #5903 demonstrates separate task runners rather than a direct translation of those aliases.
Our October source setup installed in 306 seconds and built in 1 second, then pytest stopped with three collection/setup errors. A November quickstart installed Ruff but stopped at a different point: its recipe expected a Python code block that the README did not contain. Those outcomes make command scope important. Installing a tool, synchronizing an application and preparing a contributor checkout are different jobs, even when each starts with uv.
What people use uv for
Developers report using uv for CI migration, teaching notebooks, installed personal commands and workspace development.
| Who used it | What they did | Reported outcome |
|---|---|---|
| AwayVermicelli3946, r/Python | Replaced Poetry in CI pipelines | Reported substantial time savings. |
| Rodrigo Girão Serrão, mathspp | Installed a script as a command | Ran myproj against a history file outside its project. |
| The LernerPython author | Installed packages for teaching notebooks | Reported that uv pip install --system worked. |
| NellyWhads, issue #9637 | Configured multiple projects in one workspace | Reported successful interpreter selection and testing integration. |
The mathspp example gives a concrete use for uv outside application migration. Its author turns a Python script into an installed command and invokes it against a file elsewhere on the machine. The walkthrough then edits the command's entry point in pyproject.toml. That is a useful distinction for a personal utility: the Python code, the installed command name and the package configuration each have a role in how the utility reaches your shell.
For applications, Astral's project guide describes four separate files and directories: pyproject.toml records broad requirements, .python-version selects the default interpreter, .venv contains the environment, and uv.lock records exact resolved dependencies. The guide recommends checking the lockfile into version control. This arrangement makes dependency declarations and the selected installation visible alongside the source code, rather than leaving the environment as a collection of remembered installation commands.
What happened when we ran it
Our October run installed in 306 seconds and built in 1 second; the November quickstart installed Ruff before its snippet step failed.
| Recorded check | Answer | Verdict | Why |
|---|---|---|---|
| October installation | Succeeded in 306 seconds; 35 dependencies; 163 MB on disk | Completed | The harness recorded a successful installation step. |
| October build | Succeeded in 1 second | Completed | The harness recorded a successful build step. |
| October tests | Exit 1 after 4 seconds; 0 passed, 0 failed, 3 collection/setup errors | Stopped during collection | The visible traceback reports a missing keyring import. |
| October audit | Zero advisories; packages:0 | Coverage unknown | The record does not establish which packages were scanned. |
| November clone | quickstart-lib clone step took 3 seconds | Recorded | The run identifies repository commit 469fe6513a86. |
| November installation | Ruff 0.17.5 installed in 0.8 seconds | Completed | The recipe used uv pip install ruff in a fresh virtual environment. |
| November installed size | 524 KB in the environment's site-packages | Recorded | This measurement concerns the installed environment directory. |
| November dependencies | 0 packages besides Ruff | Recorded | The recipe counted additional installed packages. |
| November snippet | No Python code block found in the README | Failed | The recipe stopped before executing its expected snippet. |
| November teardown | teardown: ok | Completed | The teardown record reports success. |
The October check used commit f3e56e1 on October 9, 2026, with a recorded configuration of 3 CPUs, 8 GB RAM and ghcr.io/astral-sh/uv:python3.12-bookworm. Our installation and build measurements describe those recorded steps. Pytest's footer names scripts/publish/test_publish.py, test/packages/built-by-uv/tests/test_package.py and test/packages/keyring_test_plugin/keyrings/test_keyring.py. The visible traceback reaches an import of backend and credentials from keyring, then reports ModuleNotFoundError: No module named 'keyring'.
Pytest reports 3 errors in 1.33s, while the outer harness records 4 seconds for the test step. These figures measure different scopes. The parser's 0 passed and 0 failed describe a command that stopped during collection, rather than three executed tests that failed. The checkout also contained 46 CI workflow files, a Dockerfile and a tests directory, as recorded in the October repository scan.
The November run record describes a fresh unprivileged container with 2 CPUs, 4 GB RAM, no published ports and no secrets. Its installation step installed Ruff 0.17.5 in 0.8 seconds, using uv pip install ruff rather than the README's uv add ruff. The clone took 3 seconds, site-packages occupied 524 KB, and no packages besides Ruff were counted. The snippet step failed, the no-snippet finding records the same stopping point, and teardown succeeded.
Where people get stuck: commands around the package manager
Task aliases, shell entry, environment variables and user installations appear as separate migration problems in GitHub discussions.
| Existing habit | Reported problem | Documented response |
|---|---|---|
| Rye or Hatch task aliases | Users want named tasks through uv run | Issue #5903 shows Poe the Poet and taskipy. |
| An interactive environment shell | Users request uv shell | Issue #1910 requests a portable activation command. |
| Pipenv .env loading | TheRealBecks reports broken local Ansible environments | Issue #1384 describes the migration failure. |
| pip install --user | An Airflow container workflow needed adaptation | potiuk describes replacing ~/.local with a virtual environment. |
Issue #5903 contains complete examples for adding Poe the Poet or taskipy and invoking their tasks through uv run. A Python entry point exposes a function as a command; the requested task aliases can describe other commands and shell behavior. Migrating a formatter-and-test task therefore requires preserving the task's actual operations, including its environment settings, rather than merely giving a Python function the same name.
In #2077, potiuk reports creating a virtual environment at ~/.local and setting VIRTUAL_ENV and PATH for an Airflow packaging workflow. In #1384, TheRealBecks reports that moving from Pipenv broke local Ansible environments that depended on .env loading. These are attributed migration histories. They identify commands and settings worth inventorying before replacing an existing installation or launch procedure.
Dependency updates have three separate meanings
uv lock --upgrade-package requests attempts a compatible lockfile update, while synchronization brings the environment into line with its requirements.
The project guide documents uv lock --upgrade-package requests as an attempt to update one package to the latest compatible version while keeping the rest of the lockfile intact. The requirement in pyproject.toml defines what versions are acceptable; uv.lock records an exact resolution. A request for a compatible update therefore operates within the declared requirement. Changing that requirement is a separate project decision.
In issue #6794, bjorhn explains that uv sync downloads modules matching a pin without changing the pin. That distinction resolves much of the ambiguity in the word upgrade. A review of an update should identify whether the change alters compatibility policy, exact resolved versions or the installed environment. Those changes can occur together, but they answer different questions and leave different changes in version control.
Editor discovery and cloud folders need explicit paths
UV_PROJECT_ENVIRONMENT controls the environment location for project workflows, according to a response in issue #1495.
The environment-location discussion in #1495 distinguishes high-level project workflows from lower-level uv pip and uv venv use. It names UV_PROJECT_ENVIRONMENT for the former, and UV_PYTHON or --python for the latter. The discussion also includes symlinking .venv. For projects stored in a synchronized folder, environment placement is a concrete configuration choice rather than something that dependency locking alone resolves.
In issue #9637, NellyWhads reports a working monorepo setup using direnv to set a project-specific UV_PROJECT_ENVIRONMENT, selecting the appropriate .venv in VSCode and reloading the window. Testing integration used the specific pyproject.toml containing that project's pytest configuration. The thread's maintainer edit also recommends python.usePythonEnvironmentsExtension: true. These instructions address interpreter discovery and test configuration, which are separate from whether the terminal installation command completed.
Project commands and standalone scripts use different environments
uv run retains extraneous packages by default, and inline script metadata makes the surrounding project's dependencies irrelevant to that script.
The project guide explicitly describes packages outside the lockfile remaining in the environment. A command can consequently find an installed package even when the lockfile does not declare it. A dependency review should inspect the declarations and the environment together. The guide also documents uv sync followed by manual activation as an alternative to executing each project command through uv run.
For a script with inline metadata, Astral says the project's dependencies are ignored, even when uv run executes inside a project. The same guide documents uv lock --script example.py, which creates an adjacent example.py.lock file. That gives standalone scripts their own dependency boundary and locking step. An application script and a portable utility can share Python syntax while requiring different environment choices.
Build isolation and auditing answer different questions
A cross-platform lockfile can require dependency metadata for packages used on other platforms, according to Astral's build-failure guide.
The build-failure guide describes resolution trying wheel metadata, then static source metadata, then a build. Installation also needs a wheel for the current platform; when no matching wheel exists, uv tries building the source distribution. This explains why dependency resolution can encounter build machinery and why the package, build backend and system configuration all belong in the diagnosis of a build error.
pip-audit recorded zero advisories; the record does not establish which packages were scanned. The October harness records packages:0, alongside its advisory result. An advisory count and a successful installation are separate outputs, just as a build result and a test result are separate outputs. Keeping those fields separate preserves the actual outcome instead of turning one successful step into a broader assessment.
Release 0.13.9 and the recorded commits
uv 0.13.9 was released on November 17, 2026; the two recorded repository commits are f3e56e1 and 469fe6513a86.
The 0.13.9 release notes identify release commit 6b2d39d and list preview support for PEP 832 .venv redirect files, lockfile changes and bug fixes. The October run predates that release, while the November run is dated November 19. Repository checkout identity and executable identity belong in separate fields when describing what a command exercised.
uv vs pip, Poetry, conda and uvx
uv documents project management and a pip interface; choosing between those workflows depends on the job you are replacing.
| Choice | Evidence-backed distinction | Decision |
|---|---|---|
| uv vs pip | Astral documents a pip-compatible interface and project management. | Keep an installation workflow when that is the job; adopt project declarations and locking when those solve a concrete problem. |
| uv vs Poetry | AwayVermicelli3946 reports CI time savings, while latkde corrects an outdated metadata comparison. | Compare your actual CI and project commands rather than assuming migration removes all workflow differences. |
| uv vs conda | The Python Developer Tooling Handbook recommends considering conda for non-Python scientific libraries. | Let those library requirements determine the environment choice. |
| uv vs manual venv | Astral documents uv run and manual activation. | Choose how commands enter the project environment. |
| uv vs pipx | The README describes isolated tool execution and installation. | Distinguish a personal installed command from an application dependency. |
| uv run vs uvx | uvx aliases uv tool run. | Use the project execution path when the project's dependencies and locked tool version matter. |
The Poetry discussion contains both a recommendation and a correction. latkde says they use both tools and prefer uv for most cases, while noting that modern Poetry supports the standard PEP 621 project table and dependency groups. That correction matters when assessing exit options: a comparison based on obsolete metadata behavior gives the migration decision the wrong starting point.
Outdated claims, corrected
Astral documents pip-style installation and standalone scripts, so project workflows are one supported route rather than the only legitimate use of uv.
The LernerPython article You're probably using uv wrong advocates projects after reporting that uv pip install --system worked for teaching notebooks. Its project preference should be read alongside Astral's documented pip interface and scripts support. The article's older main.py walkthrough is historical; the newer project guidance summarized in the research describes a packaged src layout.
A promise that uv run prevents every missing-package error is too broad. The official scripts guide demonstrates ModuleNotFoundError for an undeclared rich import, then requests rich explicitly. Chandra Kundu's project tutorial names the environment venv, whereas Astral names the default directory .venv. Astral's project guidance also places environment creation at the first project command after initialization, rather than treating initialization alone as that step.
GeekChamp's uv review says the maker publishes no additional product facts. Astral's README and project, script and build-troubleshooting guides document concrete behavior: dependency locking, environment layout, Python installation, isolated tools and source-build resolution. Those are the product details a Python developer needs when deciding which existing commands to replace.
FAQ
uv supports pip-style installation and project management, so adopting it does not require converting every installation task into a project.
How should maintenance and ownership concerns affect adoption?
The Reddit discussion raises ownership and maintenance concerns; the README documents MIT or Apache-2.0 licensing at the user's option.
Treat the ownership premise raised in r/Python as a participant's premise when reading that discussion. For an adoption decision, identify the project declarations, lockfile and uv-specific configuration you would need to replace. The README's licensing terms provide a concrete fact for that assessment, while the thread's predictions about future maintenance remain participants' opinions.
How difficult would it be to migrate away from uv if its development changed?
tdh3m points to standard pyproject.toml dependency metadata and identifies uv.lock as a uv-specific artifact.
That Reddit comment describes an exit route, including retaining project metadata and changing the build system. latkde then corrects its comparison with Poetry's metadata support. For your own project, list the lockfile, build backend and tool.uv settings alongside the commands used in CI. That inventory makes the replacement work visible without assuming every project's migration has the same cost.
What is the difference between uv run and uvx?
uvx is an alias for uv tool run, which executes a tool in an isolated environment.
The README describes uvx and uv tool install separately from project execution. Issue #5903 also discusses a development tool invoked through uvx selecting a different environment and version from the project. For a formatter pinned as a project dependency, choose the project command path deliberately; for a personal command, isolated tool installation may be the desired behavior.
How do I install Python with uv?
The README demonstrates uv python install 3.12 3.13 3.14 and uv python pin 3.11.
These documented Python commands perform different jobs: installation obtains interpreters, while pinning records the version choice for the current directory. The README also shows uv venv --python 3.12.0 for creating an environment with a specific Python version. These are documentation examples, and their displayed versions remain separate from the runtime identity of either recorded run.
How do I create and activate a virtual environment with uv?
uv venv creates an environment; the project guide shows activation commands for .venv on macOS, Linux and Windows.
The project guide shows source .venv/bin/activate and .venv\Scripts\activate, after synchronizing the project environment. It also documents running commands with uv run. Choose the command style your shell and automation use, then keep that choice explicit in setup instructions. The request for a portable uv shell command appears separately in issue #1910.
Does uv sync update dependency constraints in pyproject.toml?
In issue #6794, bjorhn explains that uv sync downloads modules matching the pin without changing it.
The project guide's compatible-upgrade command is uv lock --upgrade-package requests. Synchronization, compatible resolution and changing a declared requirement are separate operations. This distinction is useful during review: a lockfile change records a selected resolution, while changing a requirement alters the set of versions the project accepts. The issue discussion explicitly separates synchronization from pin changes.
What we have not tested yet
Neither run establishes a test of release 0.13.9. The November record identifies the cloned repository commit but does not identify the uv executable version used from the container.
The October image label does not identify actual runtime or operating-system versions. The visible traceback supports the missing keyring diagnosis; the other named collection errors need their full tracebacks before assigning causes. The November snippet failure records a recipe stopping point, rather than Ruff execution. These checks cover neither a passing upstream Rust suite nor a complete application migration, Windows, macOS, private indexes, editor workarounds, cloud synchronization or a conda scientific stack.
The Reddit ownership premise is unverified in this review. Reported CI savings are anecdotal, and the recorded checks include no controlled pip or Poetry comparison with equivalent dependencies and cache conditions. Audit scan coverage is unknown, and the advisory result provides no assessment of uv's Rust implementation or future downloads. Rendered layout, resolved links, automatic related links, recommendation modules and template content are also outside this text review.
For a migration, start with one application's actual task commands, environment variables and editor settings. Recreate its environment from declared requirements, run its existing checks and inspect changes to both pyproject.toml and uv.lock. That gives the next adoption decision a concrete project outcome, with task behavior and dependency changes visible together.


