Cheat Sheets

uv Cheat Sheet: Python Package Manager Commands (PDF)

This post contains affiliate links. If you buy through them, we may earn a small commission at no extra cost to you. Learn more.

When a Python project needs its own interpreter, a lockfile CI can trust and a few command-line tools, most teams reach for four programs. The usual set is pyenv, pip, pip-tools and pipx, each owning one piece. A single uv binary replaces all four, and it is fast enough that a cold install of six web packages finished in under two seconds on our test servers.

Original content from computingforgeeks.com - post 189988

uv has two personalities, and mixing them up causes most of the confusion. The project commands manage pyproject.toml and uv.lock for you, while uv pip is a pip-shaped interface with a few deliberate differences. This uv cheat sheet covers both, plus Python version management, tools, scripts, workspaces and publishing. We ran every command on this page on Ubuntu 26.04 and Rocky Linux 10 against uv 0.13.8 in November 2026, and every output block is what those two servers printed.

uv Cheat Sheet (Quick Reference)

The tables below are the commands you’ll reach for most, grouped by job. Every row was run on both test servers. The sections after the tables show the real output and the behaviour that is not obvious from the flag name, because that is where most uv surprises live.

Install and update uv

CommandWhat it does
curl -LsSf https://astral.sh/uv/install.sh | shInstall the latest uv and uvx into ~/.local/bin
uv self updateUpgrade a standalone install in place
uv self versionPrint the installed uv version and target
uv --versionSame version line, shorter to type

Python versions

CommandWhat it does
uv python listInstalled and downloadable interpreters
uv python list --only-installedOnly what is on disk, system ones included
uv python install 3.13 3.14Download managed CPython builds
uv python find 3.14Path of the interpreter uv would use
uv python pin 3.14Write .python-version for this directory
uv python upgrade 3.13Move a managed version to its latest patch
uv python uninstall 3.14Remove a managed interpreter
uv python dirWhere managed interpreters live

Create projects

CommandWhat it does
uv init demo-apiPackaged app: src/ layout, entry point, uv_build
uv init --no-package helloPlain app with main.py, nothing to build
uv init --lib mathlibLibrary layout ready for uv build
uv init --bare migratedOnly pyproject.toml, no extra files
uv init --python 3.13 svc313Set requires-python and .python-version at once
uv run demo-apiRun the project’s entry point
uv run python --versionRun any command inside the project venv
uv version --bump minorBump the version in pyproject.toml

Dependencies

CommandWhat it does
uv add httpx "fastapi>=0.115"Add runtime deps, lock and install
uv add --dev pytestAdd to the dev group (synced by default)
uv add --group lint ruffAdd to a named group (not synced by default)
uv add -r requirements.txtImport an existing requirements file
uv remove fastapiDrop a dependency and resync
uv tree --depth 1Direct dependencies with their groups
uv tree --outdated --depth 1Flag packages with a newer release

Lock, sync and export

CommandWhat it does
uv lockResolve and write uv.lock
uv lock --checkExit 1 if uv.lock is out of date
uv lock --upgradeRe-resolve everything to the newest allowed
uv lock --upgrade-package httpxUpgrade one package in the lock
uv syncMake .venv match the lock exactly
uv sync --lockedSync, but fail if the lock is stale
uv sync --frozenInstall from uv.lock without checking it
uv sync --no-devLeave out the dev group
uv sync --group lintAdd a named group to the sync
uv sync --all-groupsEvery dependency group
uv sync --inexactKeep packages the lock doesn’t list
uv export --format requirements.txt --no-hashes -o requirements.txtWrite the lock as requirements.txt
uv export --no-dev --no-hashesProduction export without dev tools

Scripts and one-off runs

CommandWhat it does
uv init --script report.py --python 3.13New script with an inline metadata block
uv add --script report.py richAdd a dependency to the script header
uv run report.pyRun it in a cached, throwaway env
uv lock --script report.pyWrite report.py.lock next to the script
uv run --with rich python -c "..."Add a package for one run only

Tools (uv tool and uvx)

CommandWhat it does
uv tool install ruffInstall a CLI tool in its own venv
uv tool listInstalled tools and their executables
uv tool upgrade --allUpgrade every installed tool
uv tool uninstall ruffRemove a tool
uv tool dirWhere tool environments live
uvx [email protected] --versionRun a pinned tool version without installing
uvx --from httpie http --versionRun a command whose package has another name

pip interface

CommandWhat it does
uv venvCreate .venv (no pip inside)
uv venv --python 3.14 .venv314Venv with a specific interpreter and name
uv pip install requestsInstall into the active or local venv
uv pip compile requirements.in -o requirements.txtPin a requirements.in, pip-tools style
uv pip compile requirements.in --python-version 3.12 --universalOne pin file for every platform
uv pip sync requirements.txtMake the venv match the file exactly
uv pip list / uv pip freezeInstalled packages
uv pip show requestsVersion, location and requirements
uv pip checkVerify installed packages are compatible
uv pip treeDependency tree of the venv
uv pip uninstall requestsRemove a package (not its deps)

Workspaces, build and publish

CommandWhat it does
uv init --lib packages/sharedInside a project: add a workspace member
uv add sharedDepend on a sibling member
uv sync --all-packagesInstall every member into one .venv
uv run --package api pythonRun in the context of one member
uv buildBuild sdist and wheel into dist/
uv publish --dry-runCheck files against the index, upload nothing
uv version --bump patch --dry-runPreview the next version

Cache

CommandWhat it does
uv cache dirCache location (~/.cache/uv)
uv cache size --humanCache size (preview feature)
uv cache pruneRemove unused entries only
uv cache prune --ciDrop downloaded wheels, keep built ones
uv cache cleanEmpty the whole cache

The rest of the page goes through those groups in the order you’d meet them on a new machine, with the output our servers returned and the gotchas that cost us time.

Installing and updating uv

The standalone installer is the route to take on servers, because it puts uv and uvx in your home directory and lets uv self update manage upgrades. Distro packages and pip install uv both work, but neither supports self update, so you end up upgrading uv through a second tool.

curl -LsSf https://astral.sh/uv/install.sh | sh

On Rocky Linux 10 the script finished without any PATH hint, because the default ~/.bashrc there already puts ~/.local/bin on the PATH:

downloading uv 0.13.8 x86_64-unknown-linux-gnu
installing to /home/mary/.local/bin
  uv
  uvx
everything's installed!

Ubuntu 26.04 is different. The installer prints a source $HOME/.local/bin/env line and writes that env file, and you need to source it (or open a new shell) before uv resolves. Copying that habit to Rocky fails, since no env file is created there:

/home/mary/.local/bin/env: No such file or directory

To show the upgrade path, we first installed the previous release through the versioned installer URL, which is also how you’d pin uv in a CI image, then let uv upgrade itself:

curl -LsSf https://astral.sh/uv/0.13.7/install.sh | sh # pin: older build to demo self update #https://github.com/astral-sh/uv/releases
source $HOME/.local/bin/env # Ubuntu only, Rocky has no env file
uv self update
uv self version

The update re-runs the installer, replaces the uv and uvx binaries and prints the release link for the new version. Your projects, managed Pythons and cache are left alone, so it is safe to run on a shared build host between jobs.

uv installer and uv self update output on Ubuntu 26.04

Running uv self update again reports You're already on version v0.13.8 of uv (the latest version) and exits 0, so it’s safe to put in a provisioning script. The distro differences we hit on the two servers are worth knowing before you script anything:

BehaviourUbuntu 26.04Rocky Linux 10
System Python3.14.4 (/usr/bin/python3)3.12.15 (/usr/bin/python3.12)
Installer PATH hint and ~/.local/bin/envPrinted and createdNot needed, not created
git preinstalledYes, so uv init creates .gitNo, so uv init skips .git and .gitignore
uv pip install --systemRefused: externally managed (PEP 668)Resolves, then permission denied on /usr/local

If you want the system Python and venv basics covered first, our guide to installing Python on Ubuntu 26.04 walks through pip, venv and pyenv next to uv, and the Python, Node.js, Go and Rust setup on Fedora covers the dnf side. Fedora also packages uv itself with Python downloads turned off, which our guide to uv on Fedora works through.

Managing Python versions

uv downloads standalone CPython builds, so you can run 3.13 on a server whose distro ships 3.12 without touching the system interpreter. Start by asking what is available.

uv python list

Ubuntu’s own 3.14.4 shows up next to the downloadable builds, which is how uv decides it doesn’t need to fetch anything for a >=3.14 project:

cpython-3.16.0a2-linux-x86_64-gnu                 <download available>
cpython-3.16.0a2+freethreaded-linux-x86_64-gnu    <download available>
cpython-3.15.2-linux-x86_64-gnu                   <download available>
cpython-3.15.2+freethreaded-linux-x86_64-gnu      <download available>
cpython-3.14.10-linux-x86_64-gnu                  <download available>
cpython-3.14.10+freethreaded-linux-x86_64-gnu     <download available>
cpython-3.14.4-linux-x86_64-gnu                   /usr/bin/python3.14
cpython-3.14.4-linux-x86_64-gnu                   /usr/bin/python3 -> python3.14
cpython-3.13.18-linux-x86_64-gnu                  <download available>
cpython-3.13.18+freethreaded-linux-x86_64-gnu     <download available>
cpython-3.12.16-linux-x86_64-gnu                  <download available>
cpython-3.11.18-linux-x86_64-gnu                  <download available>

Install two versions in one go, since uv fetches them in parallel.

uv python install 3.13 3.14

Ubuntu finished in 2.32s and Rocky in 5.46s, with the same builds landing on each. The gap is network, not uv, so expect your own numbers to follow your mirror’s distance.

uv python install 3.13 3.14 downloading CPython builds on Rocky Linux 10

The interpreters live under ~/.local/share/uv/python (uv python dir prints it), and uv drops python3.13 and python3.14 shims into ~/.local/bin. uv python find 3.14 returns the full path when another tool needs it:

/home/mary/.local/share/uv/python/cpython-3.14-linux-x86_64-gnu/bin/python3.14

Pinning is per directory. uv python pin writes .python-version, but it won’t write a version the project’s requires-python forbids. In a project created with the Ubuntu default of 3.14, pinning 3.13 is refused with exit code 2, so fix requires-python first and pin second. Use uv python upgrade 3.13 to move a managed version to its newest patch. Ours printed Python 3.13 is already on the latest supported patch release.

Starting a project with uv init

This is where older uv tutorials go wrong. Plain uv init now creates a packaged application: a src/ layout, a console entry point and the uv_build backend, with no main.py at all.

uv init demo-api
cd demo-api
cat pyproject.toml

The generated file pins the build backend to the uv minor series and wires a demo-api command to demo_api:main:

[project]
name = "demo-api"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.14"
dependencies = []

[project.scripts]
demo-api = "demo_api:main"

[build-system]
requires = ["uv_build>=0.13.8,<0.14.0"]
build-backend = "uv_build"

Run the entry point by name with uv run demo-api, which printed Hello from demo-api!. If you want the old single-file layout, pick the flag that matches what you’re building:

  • --no-package: a main.py app with no build system
  • --lib: a library you intend to build and publish
  • --bare: only pyproject.toml, for migrating an existing repo
  • --python 3.13: sets requires-python and .python-version together

On Rocky the same command created no .git or .gitignore, because git isn’t installed in the minimal image. Install git first if you want uv to initialise the repository for you.

Adding and removing dependencies

uv add edits pyproject.toml, resolves, writes uv.lock and installs into .venv in one step. The first call also creates the venv, so there is nothing to activate first.

uv add httpx "fastapi>=0.115"

Sixteen packages resolved in 288ms and installed in 13ms on Ubuntu. The install time is that low because uv hardlinks files from its cache instead of copying them:

Using CPython 3.14.10
Creating virtual environment at: .venv
Resolved 16 packages in 288ms
   Building demo-api @ file:///home/mary/demo-api
      Built demo-api @ file:///home/mary/demo-api
Downloading pydantic-core (2.2MiB)
 Downloaded pydantic-core
Prepared 16 packages in 110ms
Installed 16 packages in 13ms
 + annotated-doc==0.0.6
 + annotated-types==0.8.0
 + anyio==4.16.0
 + certifi==2026.10.23
 + demo-api==0.1.0 (from file:///home/mary/demo-api)
 + fastapi==0.162.5
 + h11==0.16.0
 + httpcore==1.0.9
 + httpx==0.28.1
 + idna==3.20
 + opentelemetry-api==1.45.2
 + pydantic==2.14.3
 + pydantic-core==2.50.4
 + starlette==1.10.0
 + typing-extensions==4.16.0
 + typing-inspection==0.4.5

Development tools go into dependency groups. The dev group is special: uv sync and uv run install it by default. Any other group, such as lint here, only installs when you ask for it.

uv add --dev pytest
uv add --group lint ruff

Both groups end up in a PEP 735 [dependency-groups] table at the bottom of pyproject.toml. Groups are never published with a package, so this is the right home for test and lint tools rather than optional extras.

[dependency-groups]
dev = [
    "pytest>=9.2.0",
]
lint = [
    "ruff>=0.17.5",
]

That default matters more than it looks. When we ran uv remove fastapi, uv uninstalled 10 packages, and ruff was one of them, because the resync after the removal only kept the default groups. Run uv sync --group lint or --all-groups to get it back. uv tree --outdated --depth 1 is the quick way to see what is behind. With httpx pinned to an older release it showed this.

Resolved 16 packages in 1ms
demo-api v0.2.0
├── httpx v0.27.2 (latest: v0.28.1)
└── pytest v9.2.0 (group: dev)

Migrating from a requirements file is one command in a --bare project: uv add -r requirements.txt turned flask>=3 and an unpinned requests into "flask>=3" and "requests>=2.34.2", adding a lower bound at the version it resolved.

Locking and syncing environments

uv.lock is a cross-platform lockfile with hashes for every wheel and sdist. You don’t edit it, but you do commit it, and CI should refuse to run when it disagrees with pyproject.toml. Three flags control that, and they’re easy to mix up:

  • uv lock --check: exit 1 if the lock is stale, change nothing
  • uv sync --locked: same check, then install
  • uv sync --frozen: install from the lock and never look at pyproject.toml

To see the check fire, we changed the httpx specifier from "httpx>=0.28.1" to "httpx>=0.27,<0.29". The locked 0.28.1 still satisfies the new range, yet both commands, run from inside ~/demo-api, treated the lock as stale on both distros.

uv lock --check and uv sync --locked failing on a stale uv.lock, then passing after uv lock

So treat any edit to a dependency line as a lock change and commit the two files together. --frozen is the dangerous one: after we edited pyproject.toml to require httpx==0.28.1, uv sync --frozen exited 0 and left httpx at 0.27.2, exactly as the old lock said. That’s what you want inside a Docker build that copies only the lockfile, and what you don’t want anywhere a human edits pyproject.toml. A plain uv lock then reported the change precisely:

Resolved 15 packages in 7ms
Updated httpx v0.27.2 -> v0.28.1
Removed sniffio v1.3.1

uv sync itself is exact: it removes anything the lock doesn’t select. uv sync --no-dev uninstalled pytest and its four dependencies, and the next uv sync --frozen put all five back in 10ms. Pass --inexact if something else installs into the same venv and you want uv to leave it alone. Note that uv run syncs inexactly by default, so it won’t strip extra packages before running your command.

For platforms that still want requirements.txt, export from the lock instead of running pip freeze. A freeze only records what one machine happens to have installed, while the export carries the whole cross-platform resolution.

uv export --format requirements.txt --no-hashes -o requirements.txt

The export keeps environment markers and the reason each package is there. Note the Windows-only colorama line that a pip freeze on Linux would never produce:

# This file was autogenerated by uv via the following command:
#    uv export --format requirements.txt --no-hashes -o requirements.txt
-e .
anyio==4.16.0
    # via httpx
certifi==2026.10.23
    # via
    #   httpcore
    #   httpx
colorama==0.4.6 ; sys_platform == 'win32'
    # via pytest
h11==0.16.0
    # via httpcore
httpcore==1.0.9
    # via httpx
httpx==0.28.1
    # via demo-api
idna==3.20
    # via
    #   anyio
    #   httpx
iniconfig==2.3.1
    # via pytest
packaging==26.3
    # via pytest
pluggy==1.7.0
    # via pytest
pygments==2.21.0
    # via pytest
pytest==9.2.0
typing-extensions==4.16.0 ; python_full_version < '3.15'
    # via anyio

Add --no-dev for a production image, and drop --no-hashes when the consumer is pip, so it gets --hash=sha256: lines and can verify every download. The -e . line installs the project itself, so add --no-emit-project if the target only needs the dependencies.

Running scripts with inline metadata

Single-file admin scripts are where uv saves the most hassle. PEP 723 lets a script declare its own dependencies in a comment block, and uv run builds a cached environment for it, so there’s no venv to create or forget about.

uv init --script and uv add --script writing PEP 723 inline metadata into report.py

We replaced the generated body with a small host report and added a shebang, so the file can run as a plain executable. Open the script:

vim report.py

This is the exact file we ran on both servers.

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.13"
# dependencies = [
#     "rich>=15.0.0",
# ]
# ///
import platform

from rich.console import Console
from rich.table import Table

def main() -> None:
    table = Table(title="Host report")
    table.add_column("Key")
    table.add_column("Value")
    table.add_row("host", platform.node())
    table.add_row("python", platform.python_version())
    Console().print(table)

if __name__ == "__main__":
    main()

Run it through uv, or mark it executable and call it directly.

uv run report.py
chmod +x report.py && ./report.py

The first run installed rich and its three dependencies into the cache (10ms on Ubuntu, 753ms on Rocky), and the second run started straight away. On Rocky the table reported Python 3.14.10, because the system 3.12 doesn’t meet >=3.13 and uv picked a managed build it had downloaded:

    Host report
┏━━━━━━━━┳━━━━━━━━━┓
┃ Key    ┃ Value   ┃
┡━━━━━━━━╇━━━━━━━━━┩
│ host   │ build02 │
│ python │ 3.14.10 │
└────────┴─────────┘

For scripts that run from cron, uv lock --script report.py writes a report.py.lock next to the file so the next run can’t drift to a new rich release. For a quick experiment with no file at all, uv run --with rich python -c "import rich; print(rich.__file__)" gives you rich for one command from an environment under ~/.cache/uv/archive-v0, and nothing touches your project.

Installing CLI tools with uv tool and uvx

uv tool is the pipx replacement: each tool gets an isolated venv under ~/.local/share/uv/tools and its executables are linked into ~/.local/bin.

uv tool install ruff
uv tool list

The list shows each tool with the commands it put on your PATH.

ruff v0.17.5
- ruff

uvx (short for uv tool run) runs a tool from a cached throwaway environment instead, which is the better choice for anything you run once a month. Two forms cover most cases: a pinned version with @, and --from when the command name differs from the package:

uvx [email protected] --version
uvx --from httpie http --version

The pinned ruff ran next to the installed 0.17.5 without replacing it, and httpie came from its own environment:

ruff 0.14.0
3.2.4

uv tool upgrade --all upgrades every installed tool within its constraints (ours said Nothing to upgrade), and uv tool uninstall ruff removes both the venv and the link.

Using the uv pip interface

uv pip is for repos that aren’t ready to move to pyproject.toml and uv.lock. It takes pip’s commands and most of its flags, but it isn’t pip, and the uv pip compatibility notes list the differences. These are the ones that change day-to-day behaviour:

  • Installs only into a virtual environment unless you pass --system
  • Ignores pip.conf and PIP_INDEX_URL; it reads uv.toml and UV_* variables
  • Stops at the first index that has a package, unless you set --index-strategy unsafe-best-match
  • Skips .pyc compilation unless you pass --compile-bytecode
  • Has no --user flag at all

The index behaviour is the one that bites teams with a private mirror. pip merges every index it is given and picks the best version. uv stops at the first index that has the package name, which blocks dependency-confusion attacks but surprises anyone who relied on pip’s merge. Create a venv, then install as usual.

uv venv
uv pip install requests

uv finds .venv in the current directory without activation, which is why the install below worked without a source step:

Resolved 5 packages in 5ms
Installed 5 packages in 6ms
 + certifi==2026.10.23
 + charset-normalizer==3.5.2
 + idna==3.20
 + requests==2.34.2
 + urllib3==2.8.0

The pip-tools workflow carries over directly. Put loose requirements in requirements.in, compile them to pins, then sync:

uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

With flask>=3 and requests as input, compile resolved 12 packages in 126ms on Ubuntu (361ms on Rocky) and wrote the same pip-tools format, # via comments included. Without -o it only prints to stdout. Compile also strips extras and leaves out index URLs by default; add --emit-index-url if your deploy needs them in the file. uv pip sync differs from uv pip install -r in one way that matters: it removes anything the file doesn’t list, so the venv matches the pins exactly.

Adding --universal --python-version 3.12 produces one file with markers for every platform and Python 3.12 or newer. uv downloaded a 3.12 build just to resolve it, which is handy when your laptop and the target servers differ.

The --system flag is where the two distros diverged most. Ubuntu refused outright with the PEP 668 message, while Rocky 10 has no EXTERNALLY-MANAGED marker, so uv resolved and downloaded everything before failing on file permissions:

uv pip install --system failing with permission denied on Rocky Linux 10

Adding sudo would make that Rocky install succeed and leave unmanaged packages in /usr/local that the next dnf update knows nothing about. Use a venv or uv tool install instead.

Building a workspace

A workspace is several packages sharing one lockfile and one .venv, which suits a repo with an API, a worker and a shared library. Running uv init inside an existing project registers the new directory as a member automatically:

uv init --app monorepo
cd monorepo
uv init --lib packages/shared
uv init --app packages/api

Each member call printed Adding `shared` as member of workspace (and the same for api), and the root pyproject.toml gained the members list:

[tool.uv.workspace]
members = [
    "packages/shared",
    "packages/api",
]

From packages/api, uv add shared adds the dependency and a [tool.uv.sources] entry of shared = { workspace = true }, so uv uses the local copy instead of looking on PyPI. Back at the workspace root (~/monorepo), lock, sync every member and run code in the context of one of them.

uv workspace sync --all-packages and uv run --package importing a shared member

Plain uv sync at the root installs only the root package, which is why --all-packages is there. The editable install means a change in packages/shared is visible to api right away, without a resync.

Building and publishing packages

A --lib project builds with no extra configuration, because uv_build is already declared as the backend:

uv init --lib mathlib
cd mathlib
uv build

uv builds the sdist first and then the wheel from that sdist, which catches files missing from the source distribution before your users do:

Building source distribution...
Building wheel from source distribution...
Successfully built dist/mathlib-0.1.0.tar.gz
Successfully built dist/mathlib-0.1.0-py3-none-any.whl

Before a real upload, a dry run against TestPyPI checks the files without sending them. We used a dummy token here. In CI, prefer --trusted-publishing always on GitHub Actions or a token from the UV_PUBLISH_TOKEN variable:

uv publish --dry-run --publish-url https://test.pypi.org/legacy/ --token pypi-FAKE

Both artifacts were checked and nothing was uploaded.

Checking 2 files against https://test.pypi.org/legacy/
Checking mathlib-0.1.0-py3-none-any.whl (1.3KiB)
Checking mathlib-0.1.0.tar.gz (811B)

Version bumps go through uv too. uv version --bump minor printed demo-api 0.1.0 => 0.2.0 and reinstalled the project at the new version, while --bump patch --dry-run only showed 0.2.0 => 0.2.1 without writing anything.

Measuring uv against pip

Speed is the reason most teams try uv, so we timed it. Both installers put the same six packages (flask, fastapi, httpx, requests, sqlalchemy, pydantic) into fresh Python 3.13 venvs on each 2 vCPU server. pip 26.3 ran with --no-cache-dir, uv ran once after uv cache clean and once with the cache warm, and we ran the whole set twice per server.

Serverpip, no cacheuv, cold cacheuv, warm cache
Ubuntu 26.04 (run 1 / run 2)8.53 s / 7.69 s0.64 s / 0.65 s0.05 s / 0.05 s
Rocky Linux 10 (run 1 / run 2)11.42 s / 9.59 s1.82 s / 1.92 s0.10 s / 0.26 s

Cold uv was 5 to 13 times faster than pip, and that gap is mostly network and parallel downloads. The warm-cache column is the one you feel every day: recreating a venv takes a twentieth of a second because nothing is downloaded or unpacked again. Keep the cache on fast local disk, since a cache on a different filesystem from your venvs forces copies instead of hardlinks and loses part of that.

Fixing common uv errors

Every message below came from our two servers while working through this page, and each one has a quick fix.

error: The requested Python version is incompatible with the project requires-python value

We hit it running uv python pin 3.13 in a project created with the default 3.14:

error: The requested Python version `3.13` is incompatible with the project `requires-python` value of `>=3.14`.

Lower requires-python in pyproject.toml first, or create the project with uv init --python 3.13. The same check stops uv run --python 3.12 in a >=3.13 project with The requested interpreter resolved to Python 3.12.16, which is incompatible with the project's Python requirement.

error: Failed to spawn: main.py

This one comes from following an older uv tutorial on a current release.

error: Failed to spawn: main.py
  cause: No such file or directory (os error 2)

Packaged projects from plain uv init have no main.py. Run the entry point (uv run demo-api), or create the project with --no-package if you want the single-file layout.

error: No virtual environment found

Running uv pip install requests in a directory with no .venv and no active venv returns:

error: No virtual environment found; run `uv venv` to create an environment, or pass `--system` to install into a non-virtual environment

Run uv venv and repeat the install. Don’t reach for --system to silence it, for the reasons in the next error.

error: The interpreter at /usr is externally managed

Ubuntu 26.04 marks its Python as externally managed (PEP 668), so uv pip install --system requests is refused:

Using Python 3.14.4 environment at: /usr
error: The interpreter at `/usr` is externally managed, and indicates the following:

  To install Python packages system-wide, try apt install
  python3-xyz, where xyz is the package you are trying to
  install.

  If you wish to install a non-Debian-packaged Python package,
  create a virtual environment using python3 -m venv path/to/venv.
  Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
  sure you have python3-full installed.

  If you wish to install a non-Debian packaged Python application,
  it may be easiest to use pipx install xyz, which will manage a
  virtual environment for you. Make sure you have pipx installed.

  See /usr/share/doc/python3.14/README.venv for more information.

hint: Virtual environments were not considered due to the `--system` flag

Install the apt package, use a venv, or install command-line tools with uv tool install. On Rocky Linux 10 the same command fails later with Permission denied (os error 13) on /usr/local/lib/python3.12/site-packages/, and the fix is the same.

warning: Ignoring existing virtual environment linked to non-existent Python interpreter

After uv python uninstall 3.14, the next uv run in a project whose venv used that build printed:

warning: Ignoring existing virtual environment linked to non-existent Python interpreter: `.venv/bin/python` -> `/home/mary/.local/share/uv/python/cpython-3.14-linux-x86_64-gnu/bin/python3.14`
Using CPython 3.14.4 interpreter at: /usr/bin/python3.14
Removed virtual environment at: .venv
Creating virtual environment at: .venv

uv repairs this on its own by rebuilding .venv. Ubuntu fell back to the system 3.14.4, while Rocky, with no system 3.14, quietly downloaded 3.14.10 again. Treat the warning as a sign that a project’s interpreter just changed under it, and rerun its tests.

uv sits under several of our other Python guides. The vLLM production install uses it to build the serving environment, the TensorFlow on Ubuntu guide sets up GPU and CPU venvs, and the Playwright HTML to PDF guide runs its Python half the same way. If you’d like a book that puts uv next to the rest of a modern Python toolchain (testing, linting, typing and packaging), Hypermodern Python Tooling by Claudio Jolowicz covers it, and our data science book picks cover the analysis side.

Keeping uv and its cache tidy

uv’s speed comes from a cache that only grows. On our Ubuntu server it reached 117.6MiB after this page’s work, with the managed Pythons stored separately on top. Check where it lives and how big it is before deciding what to remove.

uv cache dir
uv cache size --human

uv cache size is still a preview command, so it prints a warning before the number:

/home/mary/.cache/uv
warning: `uv cache size` is experimental and may change without warning. Pass `--preview-features cache-size` to disable this warning.
117.6MiB

Pick the cleanup that matches the machine. On a workstation, uv cache prune removes only entries nothing uses any more (4.6MiB on Ubuntu, 76.4MiB on Rocky) and keeps your installs fast. On a CI runner that saves its cache between jobs, end the job with uv cache prune --ci, which drops downloaded wheels but keeps wheels built from source, since building is the slow part. uv cache clean empties everything (96.6MiB here) and is the right call only when you suspect a corrupt entry, because the next install pays the full download cost again.

For upgrades, a small routine covers it.

  1. uv self update for uv itself
  2. uv python upgrade for managed interpreters
  3. uv tool upgrade --all for installed tools
  4. uv lock --upgrade per project, then run the tests and commit the lock

Keep the project step separate from the other three. uv never upgrades a lock on its own, so the version a project runs only changes when someone commits a new uv.lock, and that’s the one change worth a review. Watch the uv releases page for changes to defaults, because the uv init layout change shows uv will alter what a command creates between minor versions. More printable references live on our Linux and DevOps cheat sheets page.

Keep reading

Claude Code Cheat Sheet: Commands, Shortcuts and Flags (PDF) AI Claude Code Cheat Sheet: Commands, Shortcuts and Flags (PDF) OpenAI Codex CLI Cheat Sheet: Shortcuts, Commands, Flags (PDF) AI OpenAI Codex CLI Cheat Sheet: Shortcuts, Commands, Flags (PDF) macOS Keyboard Shortcuts Cheat Sheet (Golden Gate and Tahoe) Cheat Sheets macOS Keyboard Shortcuts Cheat Sheet (Golden Gate and Tahoe) DNF Cheat Sheet: dnf5 on Fedora, dnf on Rocky Linux 10 (PDF) Cheat Sheets DNF Cheat Sheet: dnf5 on Fedora, dnf on Rocky Linux 10 (PDF) Windows Run Commands Cheat Sheet: .msc, .cpl, ms-settings (PDF) Cheat Sheets Windows Run Commands Cheat Sheet: .msc, .cpl, ms-settings (PDF) Wget Cheat Sheet: Resume, Mirror, Retries, Auth and Spider Cheat Sheets Wget Cheat Sheet: Resume, Mirror, Retries, Auth and Spider

Leave a Comment

Press ESC to close