How to Install and Use uv on Ubuntu 26.04 and 24.04

• Use Ubuntu 26.04 or 24.04 Desktop or Server, a Bash terminal and internet access. Ubuntu on WSL uses these Linux commands inside its Ubuntu terminal.
• You need sudo only for Ubuntu packages. Run the uv installer and project commands as your normal user.
• Keep Ubuntu’s /usr/bin/python3. Do not replace it, remove it or use sudo uv to install project packages.
• Choose one uv installation route. The practice project uses Python 3.12 as a deliberate example, not as a claim about the newest Python.

Open a terminal with Ctrl+Alt+T on Ubuntu Desktop and check:

cat /etc/os-release
type -a uv uvx

A command-not-found message is expected if uv is absent. If it is already installed, run uv --version and identify how you installed it before adding another copy. The first PATH match is the one your shell runs.

These packages download HTTPS files and let you inspect the installer:

sudo apt update
sudo apt install curl ca-certificates less

APT may report that they are already installed. Review its proposed changes before confirming. You do not need Rust or a compiler to use uv’s prebuilt installer.

The installer runs downloaded code under your account. Save it first so you can read it. Keep these commands and the next step in the same terminal:

uv_setup_dir=$(mktemp -d) &&
curl --proto '=https' --tlsv1.2 -LsSf https://astral.sh/uv/install.sh -o "$uv_setup_dir/install.sh" &&
less "$uv_setup_dir/install.sh"

Press q to leave less. If the download failed, stop and fix that error. Continue only if you trust Astral and are comfortable running this script. HTTPS protects the connection; inspection is not an independent security audit.

Run the saved script without sudo:

sh "$uv_setup_dir/install.sh"

For the default installation, load the environment file it creates and check both commands:

Continue to create your first project. The pipx route below is an alternative installation, not another required step.

Choose this instead of the standalone installer:

sudo apt update
sudo apt install pipx
pipx ensurepath

Close and reopen the terminal after ensurepath. If APT cannot find pipx, check your Ubuntu repository configuration, including Universe. pipx keeps uv in its own environment rather than installing it into Ubuntu’s system Python.

In the new terminal, run:

pipx install uv
uv --version
uvx --version
pipx list

Use pipx upgrade uv for updates and pipx uninstall uv for removal. Do not use uv self update for this route. Avoid sudo pip install uv or bypassing Ubuntu’s externally-managed-environment protection.

Use a unique directory so these steps cannot overwrite an existing project:

uv_demo_dir=$(mktemp -d "$HOME/uv-demo.XXXXXX") &&
cd "$uv_demo_dir" &&
uv init --no-package --name ubuntu-uv-demo --python 3.12 --vcs none

If any command fails, stop here. --no-package requests a simple script project rather than a distributable package. --vcs none skips Git setup. uv creates starter files and records the requested Python version; the environment and lockfile are created when needed. Run pwd and save the directory path so you can return later.

Declare Rich as a project dependency:

uv add rich

uv resolves the dependency, updates pyproject.toml and uv.lock, and installs packages into .venv. It can download a suitable Python interpreter if one is missing. Installing uv itself did not require Python.

The following command replaces only the generated main.py in this new practice project. Do not run it in an existing project containing your own work:

cat > main.py <<'PY'
import sys

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


def main():
    table = Table(title="Ubuntu Python project")
    table.add_column("Check")
    table.add_column("Result")
    table.add_row("Python", sys.version.split()[0])
    table.add_row("Environment", ".venv" if sys.prefix != sys.base_prefix else "system")
    table.add_row("Rich import", "Working")
    Console().print(table)


if __name__ == "__main__":
    main()
PY

Use uv to select the project environment:

uv run main.py
uv run python -c "import sys; print(sys.executable)"

Expect a table showing a Python 3.12 patch version, .venv and Working. The executable path should end in /.venv/bin/python. Exact patch numbers, colors and table borders can vary. There is no need to activate the environment before using uv run.

From the practice project, run:

uv tree

Rich can depend on other packages. These indirect, or transitive, dependencies are resolved in the lockfile too. You normally declare the libraries your own code uses directly.

Ruff checks Python code for common mistakes. Keep it in the development dependency group:

uv add --dev ruff
uv run ruff check main.py

The example should report All checks passed!. This is a lint check, not an application test. The dev group is included by default. Use uv remove --dev ruff if you no longer want it.

Save or commit the working project first. To update Rich within its declared version constraints:

uv lock --upgrade-package rich
uv sync
uv run main.py

The first command updates the lockfile; the second installs the selected versions. Review changed files and check your program afterward. To reconsider all dependency versions within their constraints, use uv lock --upgrade, then sync and run your project checks. A routine sync does not automatically select every newly released version.

This demonstration uses a library the example does not import:

uv add humanize
uv remove humanize

Both commands update project metadata, the lockfile and the environment. Do not remove Rich while main.py still imports it. Avoid mixing manual pip installs into a uv-managed project: packages missing from project declarations can disappear on the next exact sync.

uv sync performs an exact sync by default. It can remove packages from the project environment if they are not selected by the project’s dependencies and groups. Declare needed packages with uv add. Do not point uv at a shared environment containing unrelated work.

Close editors or processes using this practice environment first. This block renames the local .venv to a backup, then creates a replacement from the lockfile. Run it only inside the practice project:

if [ -d .venv ] && [ ! -e .venv.backup ]; then
    mv .venv .venv.backup &&
    uv sync --locked &&
    uv run --locked main.py
else
    printf '%s\n' 'Stop: .venv is absent or .venv.backup already exists.'
fi

The same table should appear. The backup remains until you remove it deliberately. If recreation fails, keep that backup, fix the reported issue and retry uv sync --locked. A moved virtual environment is not a portable runnable backup; restore its original name before trying to reuse it.

uv can use an existing compatible interpreter or download one managed separately from Ubuntu:

uv python list
uv run python --version
/usr/bin/python3 --version

These last two versions can differ. The project uses its selected interpreter; Ubuntu keeps its own system Python. uv-managed downloads come from Astral’s python-build-standalone distributions, not Ubuntu APT packages.

The practice project already requests this version. For another project, check its Python requirements before changing the selection:

uv python install 3.12
uv python pin 3.12
uv sync
uv run python --version

Pinning writes .python-version. It does not rewrite the project’s requires-python compatibility range. If those requirements conflict, read the error and choose a compatible version rather than claiming unsupported compatibility. Do not use uv’s optional default-executable feature to replace your usual python3 for this exercise.

If you want a standalone ruff command outside projects:

uv tool install ruff
uv tool update-shell

Open a new terminal, then run ruff --version. Update this standalone tool with uv tool upgrade ruff, list it with uv tool list, or remove it with uv tool uninstall ruff. These operations are separate from your project’s Ruff dependency.

For the upstream script installation:

uv self update
uv --version

This updates the manager. It does not upgrade all your project dependencies, standalone tools or every Python interpreter.

For the pipx route:

pipx upgrade uv
uv --version

Keep using pipx for this installation. If the version still looks unchanged, inspect type -a uv for another copy earlier on PATH.

For a default standalone install, check whether the binary exists, then load the environment file:

ls -l "$HOME/.local/bin/uv" "$HOME/.local/bin/env"
. "$HOME/.local/bin/env"
uv --version
type -a uv

If either file is absent, do not keep sourcing it. Check the installer output or your custom installation path. For pipx, run pipx ensurepath and reopen the terminal. Do not copy binaries into /usr/bin as a PATH repair.

This usually comes from trying to install uv with pip into Ubuntu’s system Python. Use the standalone installer or the pipx route above. Do not delete the EXTERNALLY-MANAGED marker or add --break-system-packages as a workaround.

Check the project directory and selected interpreter:

pwd
ls pyproject.toml uv.lock
uv sync --locked
uv run main.py
uv run python -c "import sys; print(sys.executable)"

A bare python3 main.py may use Ubuntu’s interpreter instead of .venv. Use uv run, and select the same environment in the editor. For your own project, add missing direct dependencies with uv add.

Read the Python range and package conflict in the error. A requested interpreter must satisfy requires-python and package requirements. Inspect:

cat .python-version
cat pyproject.toml
uv python list

Install a compatible version and pin it deliberately. Do not solve a conflict by replacing /usr/bin/python3 or blindly removing version constraints. Some packages do not yet support a newly released Python.

Some dependencies lack a compatible prebuilt wheel and must compile locally. Read that package’s build instructions. A compiler error may require Ubuntu build-essential; a missing library header needs that library’s development package. System python3-dev headers may not match a uv-managed interpreter. Do not install unrelated packages or use sudo uv to bypass the failure.

Check the connection, system time and certificate bundle:

date -Is
sudo apt install --reinstall ca-certificates
curl --proto '=https' --tlsv1.2 -fsSI https://astral.sh/uv/install.sh

Correct an inaccurate clock. On a managed network, use your organization’s trusted certificate and proxy settings; current uv supports --system-certs when the required certificate is in the system trust store. Do not disable TLS verification. A blocked package index or Python download may need separate network access.

Retry the same installation route. If uv works and the problem was a project download, return to the directory containing pyproject.toml and run uv sync --locked, then uv run --locked main.py. If uv reports a stale lockfile after an intentional metadata edit, review that change and run uv lock before syncing. Keep your source and lockfile while repairing an environment.

Do this while uv still works:

uv tool list
uv python list --only-installed
uv cache dir
uv python dir
uv tool dir
type -a uv uvx

Removing the uv binaries does not delete your projects, their .venv directories, managed Python installations or installed tools. Removing a managed interpreter can break environments that reference it.

If you installed standalone Ruff in the optional section, remove it before uv:

uv tool uninstall ruff

This affects the standalone tool, not a project dependency. You can also run uv cache clean to clear cached downloads and builds. Keep the cache if you want to avoid downloading those files again. Do not recursively delete the paths printed above without inspecting their contents and dependent environments.

Only use this block if type -a confirms that your intended standalone installation uses these exact default paths. The -i option asks before each file is removed:

rm -i "$HOME/.local/bin/uv" "$HOME/.local/bin/uvx"

For a custom installation, inspect and remove its exact binary files instead. Do not delete the shared ~/.local/bin directory or its env file: other applications can use them. Inspect your shell startup configuration before removing any installer-added PATH entry.

Use this alternative for the pipx installation:

pipx uninstall uv

Do not manually remove pipx-managed command links using the standalone block. Keep pipx if you use it for other applications.

• Working on projects explains the project workflow.
• Running scripts covers single-file scripts with their own dependency metadata.
• Using tools explains isolated command-line applications.
• Storage locations explains what uv stores and where.