Skip to content

# Use the uv Backend

pipx can use uv to create virtual environments, install packages, and run ephemeral apps in place of pip and venv. The backend turns on when uv is reachable; flip it per command (`--backend`) or globally (`PIPX_DEFAULT_BACKEND`).

> This page covers pipx using uv to create venvs and install packages. The pipx CLI surface stays the same. For a side-by-side comparison with `uv tool` (Astral's standalone command), see pipx vs uv tool.

## Why use it

- uv creates venvs faster than `python -m venv`. The venv ships without pip.
- uv resolves and installs faster than pip on large dependency trees.
- `pipx run` execs `uv tool run`, picking up uv's cross-invocation cache.

## Enable it

Two ways to expose uv to pipx:

1. Install pipx with the `uv` extra. pipx prefers the bundled binary when present:

       pipx install pipx[uv]

2. Install uv however you like (`brew install uv`, `cargo install uv`, etc.) and put it on `PATH`. pipx picks it up automatically.

When uv is available, pipx defaults to it for new venvs. Existing venvs keep their original backend; the choice lives in each venv's metadata.

## Choose a backend explicitly

    pipx install black --backend pip          # force pip + venv
    pipx install ruff --backend uv            # force uv (errors if uv is not available)
    PIPX_DEFAULT_BACKEND=uv pipx install ruff # global override via environment
    pipx environment --value PIPX_RESOLVED_BACKEND  # see what pipx will use right now

`install`, `install-all`, `inject`, `upgrade`, `upgrade-all`, `reinstall`, `reinstall-all`, and `run` all accept `--backend`. Run `pipx reinstall NAME --backend uv` to switch an already-installed venv.

## What changes under the uv backend

- pipx creates new venvs with `uv venv`. The venv contains no `pip` and no `pipx_shared.pth` file.
- `pipx runpip` runs `uv pip <args> --python <venv>/bin/python`. uv rejects flags it doesn't understand instead of pipx silently dropping them.
- `pipx run` execs `uv tool run`; the cache lives in uv's cache directory. Pass `--no-cache` to skip it.
- `pipx run script.py` execs `uv run --script script.py` for PEP 723 inline scripts.

## Limitations

- `pipx install pip --backend uv` errors out. A uv venv has no pip, so the result would be inconsistent. Use `--backend pip` instead.
- `pipx run --backend uv` does not honor `[pipx.run]` entry points; `uv tool run` only sees standard console scripts. Use `--backend pip` if your package declares them.
- Some `--pip-args` values have no `uv tool run` equivalent (for example `--editable`, `--no-build-isolation`). pipx errors instead of silently dropping them. Use `--backend pip` for those flows.
- `pipx run --backend uv` against URL or named-pipe scripts falls back to a pipx-managed venv: `uv run --script` reads PEP 723 metadata off disk, and there is no on-disk path for content fetched at runtime. pipx logs a warning when this fallback fires.

## Cache layout

`pipx run` under the uv backend caches in `UV_CACHE_DIR` instead of `PIPX_VENV_CACHEDIR`. Switching the default backend on a host that already used `pipx run` leaves the old pipx cache behind: `pipx environment` prints both paths so you can inspect them and remove the unused one manually. The 14-day expiry sweep that pipx applies to its own venv cache does not extend to uv's cache, which uv manages on its own schedule (`uv cache clean`).