Python uv cheat sheet#

Python uv common usage cheat sheet, but doesn't cover all the features.

Init project#

uv init can have 3 templates: --app (by default), --lib and --package.

[project.scripts]
pkg-1 = "pkg_1:main"

Add dependencies#

optional-dependencies vs dependency-groups#

Ref:

• UV's Dependency fields
• https://github.com/astral-sh/uv/issues/8981#issuecomment-2466787211

optional-dependencies are part of the published metadata for your package, while dependency-groups are only visible when working with your package locally

Add to project.dependencies as main dependencies#

uv add fastapi

Could be installed by end users with uv pip install temp

[project]
name = "temp"
...
dependencies = [
    "fastapi>=0.116.1",
]

Add to project.optional-dependencies as extra packages#

uv add aiohttp --optional aio

Could be installed by end users with uv pip install temp[aio]

[project]
name = "temp"
...
[project.optional-dependencies]
aio = [
    "aiohttp>=3.12.15",
]

Add to dependency-groups for local development#

uv add ruff --dev
# or
uv add ruff --group dev

uv add ty --group typing

Dependencies declared in the dependency-groups part are not added to the package metadata, so end users cannot install them directly.

[project]
name = "temp"
...
[dependency-groups]
dev = [
    "ruff>=0.12.4",
]
typing = [
    "ty>=0.0.1a19",
]

Add to dependency sources#

Dependency sources are for local development only.

uv add git+https://github.com/encode/httpx
uv add --editable ../temp1/lib_1

[project]
name = "temp"
...
[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx" }
lib-1 = { path = "../temp1/lib_1", editable = true }

Declare conflicting dependencies#

uv supports explicit declaration of conflicting dependency groups. For example, to declare that the optional-dependency groups extra1 and extra2 are incompatible:

[tool.uv]
conflicts = [
    [
      { extra = "extra1" },
      { extra = "extra2" },
    ],
]

Or, to declare the development dependency groups group1 and group2 incompatible:

[tool.uv]
conflicts = [
    [
      { group = "group1" },
      { group = "group2" },
    ],
]

tool.uv.environments vs tool.uv.required-environments#

tool.uv.environments forces uv to only resolve the dependencies and cache the defined environments, whereas tool.uv.required-environments will only ensure the required environments are always available, but other environments (the wheel files) could still be resolved and cached.

[tool.uv]
environments = [
    "sys_platform == 'darwin'",
    "sys_platform == 'linux'",
]

[tool.uv]
required-environments = [
    "sys_platform == 'darwin' and platform_machine == 'x86_64'"
]

tool.uv.required-environments is useful when some packages (like PyTorch) have only wheels (no sdist), and its wheels are not available for all platforms.

Example:

Say a package foo publishes only linux platform wheels, and no sdist:

• foo-1.0.0-cp311-cp311-manylinux_x86_64.whl

If you're on Linux, and run uv add foo:

• With no required-environments → ✅ works (Linux wheel available, resolution succeeds). uv only guarantees installability for your own environment.
• With required-environments = ["sys_platform == 'darwin'"] → ❌ fails (no macOS wheel, and no sdist to build one). With this settings, your colleagues on macOS won't see surprisingly foo in the pyproject.toml

Dependency overrides#

If you want to install a version of a package that is resolved as conflict with existing dependencies, but you're sure it's compatible or you want to test it intentionally, you can use dependency overrides to force uv to install a specific version of a package.

[tool.uv]
override-dependencies = [

    # Always install Werkzeug 2.3.0, regardless of whether
    # transitive dependencies request a different version.
    "werkzeug==2.3.0",

    # Install pydantic>=2.0 even though
    # a transitive dependency declares the requirement pydantic>=1.0,<2.0
    "pydantic>=1.0,<3",
]

While constraints can only reduce the set of acceptable versions for a package, overrides can expand the set of acceptable versions, providing an escape hatch for erroneous upper version bounds. As with constraints, overrides do not add a dependency on the package and only take effect if the package is requested in a direct or transitive dependency.

Install dependencies#

[project]
name = "temp"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "fastapi>=0.116.1",
]

# this is the optional extra part, useful for end user
[project.optional-dependencies]
aio = [
    "aiohttp>=3.12.15",
]

# this is the local development groups part, useful for developers
[dependency-groups]
dev = [
    "ruff>=0.12.4",
]
typing = [
    "ty>=0.0.1a19",
]
all = [
    {include-group = "dev"},
    {include-group = "typing"},
]

$ uv sync --locked --no-dev
Resolved 21 packages in 33ms
The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.
To update the lockfile, run `uv lock`.

--locked vs --frozen vs --no-sync#

official doc: https://docs.astral.sh/uv/concepts/projects/sync/#automatic-lock-and-sync

uv.lock file related:

• --locked: If the lockfile is not up-to-date, uv will raise an error instead of updating the lockfile. --locked could be considered as --ensure-locked.
• --frozen: Use the lockfile without checking if it is up-to-date, no error will be raised.

venv related:

• --no-sync: Do not update the venv. |

--resolution lowest-direct and --resolution lowest#

With --resolution lowest, uv will install the lowest possible version for all dependencies, both direct and indirect (transitive). --resolution lowest

Alternatively, --resolution lowest-direct will use the lowest compatible versions for all direct dependencies, while using the latest compatible versions for all other dependencies. uv will always use the latest versions for build dependencies.

--resolution lowest-direct is easier than --resolution lowest as it only affects direct dependencies, so it is less likely to cause dependency conflicts:

$ uv sync --resolution lowest
Ignoring existing lockfile due to change in resolution mode: `highest` vs. `lowest`
  × Failed to build `idna==0.2`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)

      [stderr]
      Sorry, Python 3 not yet supported

      hint: This usually indicates a problem with the package or the build environment.
  help: `idna` (v0.2) was included because `temp` (v0.1.0) depends on `httpx` (v0.28.1) which depends on
        `idna`

Whereas --resolution lowest-direct works fine for the same project:

$ uv sync --resolution lowest-direct
Ignoring existing lockfile due to change in resolution mode: `highest` vs. `lowest-direct`
Resolved 26 packages in 330ms
Uninstalled 3 packages in 10ms
Installed 3 packages in 9ms
 - fastapi==0.116.1
 + fastapi==0.115.1
 - ruff==0.12.10
 + ruff==0.12.4
 - starlette==0.47.3
 + starlette==0.38.6

Reproducible builds#

• If you're using uv.lock with Dockerfile to build your application, you could use uv sync --locked --no-install-project --no-dev to ensure reproducible builds, or even the image itself is reproducible. See Using uv in Docker for more information.
• If you're not using uv.lock, and you previously (on 2025-09-07) used uv pip install -r requirements.txt to install dependencies, and not all the dependencies and transitive dependencies are pinned in requirements.txt. One day there's bug in the production, you want to reproduce the same environment as before. One of the ways is to use uv pip install -r requirements.txt --exclude-newer 2025-09-07 to exclude any package released after 2025-09-07. See Reproducible resolutions for more information. We can also add exclude-older in [tool.uv] in pyproject.toml to make it permanent.

link-mode: clone, copy, hardlink, symlink#

Possible values:

• clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory. With copy-on-write (COW), initially no extra disk space is used as long as the dependencies are cached, we're using shared cache files. But if you modify the code of a package, extra disk space will be used to store the modified files. To ensure your modification to the dependencies won't impact other projects which are using the same dependencies from the shared cache. This mode minimizes disk space usage, but it requires a filesystem that supports copy-on-write, such as Btrfs or APFS. If the filesystem doesn't support copy-on-write, uv will fallback to copy mode.
• copy: Copy packages from the wheel into the site-packages directory. This is also the default mode for traditional pip install, useful if you want to modify dependencies' code for debugging purpose.
• hardlink: Hard link packages from the wheel into the site-packages directory. fallbacks to copy mode if the cache and the venv are on different filesystems.
• symlink: Symbolically link packages from the wheel into the site-packages directory, use with caution as uv cache clean will break all installed packages.

[tool.uv]
link-mode = "copy"

or export UV_LINK_MODE=copy or --link-mode=copy in the command line.

Bytecode compilation#

Unlike pip, uv does not compile .py files to .pyc files during installation by default (i.e., uv does not create or populate __pycache__ directories). To enable bytecode compilation during installs, pass the --compile-bytecode flag to uv pip install or uv pip sync, or set the environment variable UV_COMPILE_BYTECODE=1.

Skipping bytecode compilation can be undesirable in workflows; for example, we recommend enabling bytecode compilation in Docker builds to improve startup times (at the cost of increased build times).

Concurrent install#

As per uv's documentation, concurrent installations are supported even against the same virtual environment. uv applies a file-based lock to the target virtual environment when installing, to avoid concurrent modifications across processes.

Dependencies tree#

List outdated packages#

• uv tree --outdated or uv tree --outdated | grep latest: display a list of outdated packages with their latest public versions, no matter whatpyproject.toml declares.
• uv lock --check: check if uv.lock is up-to-date with pyproject.toml.

Upgrade packages and uv.lock#

Upgrade pyproject.toml#

The only way to change the package version constraints is to edit manually the pyproject.toml file directly. After making changes to pyproject.toml, you should run uv sync to upgrade the venv dependencies and the uv.lock file accordingly. Or uv lock to upgrade only the uv.lock file without changing the venv dependencies.

Upgrade uv.lock#

uv.lock file can be updated by uv lock,uv sync,uv run,uv add,uv remove.

Integrations#

Check this doc for more information on integrations with other tools and platforms (Docker, Jupyter, Github Actions, Pre Commit, PyTorch FastAPI, etc.).

Build#

Build with rust, C, C++, CPython backend#

uv can also build with extension module by --build-backend flag to work with Rust and C, C++, CPython etc.

Build isolation#

uv build isolation is by default, but some packages need to build against the same version of some packages installed in the project environment. For example, flask-attn, deepspeed, cchardet, etc.

For a list of packages that are known to fail under PEP 517 build isolation, see #2252.

Caching#

• uv cache dir: show the cache directory.
• uv cache clean: clear the cache entirely.
• uv cache clean ruff: clear only the ruff package cache.
• uv cache prune: safely removes all unused cache entries.
• uv sync --refresh or uv pip install --refresh: force revalidate cached data for all dependencies, use --refresh-package ruff to revalidate only ruff.

Caching in CI#

As per uv's documentation on Caching in continuous integration, it's recommended to use uv cache prune --ci at the end of the CI, to remove all pre-built wheels and unzipped source distributions from the cache, but retain any wheels that were built from source.

There's an example of using this in Github Actions. It also provides enable-cache: true to achieve the same effect.

Run#

Run single script file with isolated environment#

https://docs.astral.sh/uv/concepts/projects/run/#running-scripts

# /// script
# dependencies = [
#   "httpx",
# ]
# ///

import httpx
print(httpx.__file__)

$ uv pip show httpx
Name: httpx
Version: 0.28.1
Location: /home/xiang/git/copdips.github.io/.venv/lib/python3.13/site-packages
Requires: anyio, certifi, httpcore, idna
Required-by: fastapi-cloud-cli

$ uv run example.py

/home/xiang/.cache/uv/environments-v2/example-b91cf8387ef5699e/lib/python3.13/site-packages/httpx/__init__.py

Run inline script#

uv run --with httpx python -c "import httpx; print(httpx.__file__)" to run an inline script. httpx will be installed in an isolated environment.

Tools#

uvx and uv tool run and uv run and raw command#

uvx and uv tool run are the same to run command in an isolated environment. They run uv tool install in the background

uv run is normally used to run a command in the current environment. But will auto upgrade the package based on pyproject.toml dependencies constraints. Whereas the raw command will not.

$ grep ruff pyproject.toml
    "ruff>=0.12.4",

$ uv pip install ruff==0.12.0
Resolved 1 package in 7ms
Uninstalled 1 package in 0.50ms
Installed 1 package in 3ms
 - ruff==0.12.4
 + ruff==0.12.0

$ ruff --version
ruff 0.12.0

$ uv pip tree | grep ruff
ruff v0.12.0

$ uv run --no-project ruff --version  # (1)
ruff 0.12.0

$ uv run ruff --version  # (2)
Uninstalled 1 package in 0.62ms
Installed 1 package in 3ms
ruff 0.12.4

$ ruff --version
ruff 0.12.4

$ uv pip tree | grep ruff
ruff v0.12.4

1. uv run --no-project ruff --version will use the version of ruff installed in the current environment (0.12.0). The --no-project flag tells uv to not consider the current project (pyproject.toml) and its dependencies.
2. uv run ruff --version upgrade automatically ruff version form 0.12.0 to 0.12.4 as constrainted in pyproject.toml

tools directory#

uv tool dir to show the directory where tools are installed.

$ uv tool dir
/home/xiang/.local/share/uv/tools

upgrade#

• uv tool upgrade ruff to upgrade ruff.
• uv tool upgrade ruff --reinstall to upgrade ruff and all its dependencies.

Cleanup#

The tool will be installed in an isolated environment in the user's cache directory. Use uv cache clean to clean up the cache.

Workspace#

To be continued.

Migrating from pip requirements files to uv#

Say a project uses requirements.txt to manage dependencies, there's no setup.py, the build config is declared in the pyproject.toml and now we want to migrate to uv with pyproject.toml.

Before the migration, there're 3 req files:

requirements/
  base.txt
  dev.txt
  docs.txt

and they're declared as dynamic dependencies in pyproject.toml.

[project]
name = "fastapi-demo"
dynamic = ["version", "dependencies", "optional-dependencies"]

[tool.setuptools.dynamic]
version = { file = ["VERSION"] }

[tool.setuptools.dynamic.dependencies]
file = ["requirements/base.txt"]

[tool.setuptools.dynamic.optional-dependencies]
dev = { file = ["requirements/dev.txt"] }
docs = { file = ["requirements/docs.txt"] }

Now need to remove the dynamic dependencies part in pyproject.toml, change to static dependencies, like below:

[project]
name = "fastapi-demo"
- dynamic = ["version", "dependencies", "optional-dependencies"]
+ dynamic = ["version"]

[tool.setuptools.dynamic]
version = { file = ["VERSION"] }

- [tool.setuptools.dynamic.dependencies]
- file = ["requirements/base.txt"]

- [tool.setuptools.dynamic.optional-dependencies]
- dev = { file = ["requirements/dev.txt"] }
- docs = { file = ["requirements/docs.txt"] }

And run the pip req file to uv migration with following command:

rm uv.lock

deactivate && rm -rf .venv

uv venv
# or: uv venv -p 3.13.9

# Add all base dependencies as main dependencies at once
grep -v '^#' requirements/base.txt | grep -v '^$' | xargs -I {} uv add {}

# Add all docs dependencies as extra at once
grep -v '^#' requirements/docs.txt | grep -v '^$' | xargs -I {} uv add --extra docs {}

# Add all dev dependencies as dev group at once
grep -v '^#' requirements/dev.txt | grep -v '^$' | xargs -I {} uv add --dev {}

rm -rf requirements/

Future full installation could be done by:

uv sync --frozen --all-extras --all-groups