# pipx

> pipx installs and runs end-user Python applications in isolated environments. It fills the same role as macOS’s brew, JavaScript’s npx, and Linux’s apt. Under the hood it uses uv when available and pip otherwise, but unlike either it creates a separate virtual environment for each application, so their dependencies never collide and an uninstall leaves nothing behind.

The documentation follows the Diátaxis framework: tutorials to learn pipx by doing, how-to guides for specific tasks, a reference for the CLI and environment, and explanation for how pipx works and how it compares to other tools.

## Start here
- [pipx overview](https://pipx.pypa.io/latest/index.html): pipx installs and runs end-user Python applications in isolated environments. It fills the same role as macOS’s brew, JavaScript’s npx, and Linux’s apt. Under the hood it uses uv when available and pip otherwise, but unlike either it creates a separate virtual environment for each application, so their dependencies never collide and an uninstall leaves nothing behind.
- [Tutorials](https://pipx.pypa.io/latest/tutorial/index.html): Step-by-step lessons that take you from zero to productive with pipx. Start at the top if you are new.
- [How-to guides](https://pipx.pypa.io/latest/how-to/index.html): Task recipes for pipx. Each guide states a goal, walks through the steps, and ends with a check that the change took effect. They assume pipx is already installed unless the guide is about installing it.
- [Reference](https://pipx.pypa.io/latest/reference/index.html): Technical reference for pipx: the command-line interface, environment variables, exit codes, machine-readable output, and on-disk metadata.
- [Explanation](https://pipx.pypa.io/latest/explanation/index.html): Design rationale and background. Read these to understand why pipx works the way it does.

## Tutorials
- [Getting started](https://pipx.pypa.io/latest/tutorial/getting-started.html): This tutorial covers the core pipx workflow: install an application, run it, upgrade it, and remove it. Work through it top to bottom with one small package, and you will know every command you need day to day.
- [Installing applications](https://pipx.pypa.io/latest/tutorial/install-applications.html): getting-started walked through the install → list → run → uninstall cycle with the toy pycowsay package. This tutorial repeats it with a real tool so you can see how a package’s name and its apps differ.
- [Running applications](https://pipx.pypa.io/latest/tutorial/run-applications.html): pipx run downloads and runs a Python application in a one-time, temporary environment, then leaves your system untouched. Reach for it to scaffold a new project, check an app’s help text, or try a tool without committing to an install.

## How-to guides
- [Install pipx](https://pipx.pypa.io/latest/how-to/install-pipx.html): Get pipx onto your system and add its app directory to your PATH.
- [Upgrade pipx](https://pipx.pypa.io/latest/how-to/upgrade-pipx.html): Move pipx itself to the latest release. Pick the method that matches how you installed it.
- [Manage installed apps](https://pipx.pypa.io/latest/how-to/manage-installed-apps.html): List, upgrade, and remove the apps pipx manages, then confirm each change.
- [Run scripts](https://pipx.pypa.io/latest/how-to/run-scripts.html): Run an app or a script in a temporary environment with pipx run, without installing it first. pipx downloads the package, caches the environment, and runs the app. Under the uv backend, pipx hands packages to uv tool run and local scripts with inline metadata to uv run --script, so uv’s cache applies instead of pipx’s.
- [Inject packages](https://pipx.pypa.io/latest/how-to/inject-packages.html): Add extra packages into an existing pipx-managed environment with pipx inject.
- [Pin packages](https://pipx.pypa.io/latest/how-to/pin-packages.html): Hold an installation at its current version so upgrades skip it until you unpin.
- [Expose apps](https://pipx.pypa.io/latest/how-to/expose-apps.html): Control which apps, manual pages, and shell completions an environment links onto your PATH, without rebuilding it.
- [Tool manifest](https://pipx.pypa.io/latest/how-to/tool-manifest.html): Declare a set of pipx tools in one file and install, upgrade, or prune them as a unit with pipx manifest.
- [Configure paths](https://pipx.pypa.io/latest/how-to/configure-paths.html): Choose where pipx stores environments, apps, manual pages, and shell completions, and how it installs for all users.
- [Shell completions](https://pipx.pypa.io/latest/how-to/shell-completions.html): Enable tab completion for pipx and for the apps it installs.
- [Move installation](https://pipx.pypa.io/latest/how-to/move-installation.html): Relocate your pipx directory to a new location and rebuild the environments there.
- [Standalone Python](https://pipx.pypa.io/latest/how-to/standalone-python.html): Install an app under a Python interpreter downloaded from python-build-standalone instead of the system one. Reach for this when the system Python lacks the version you need, or when a distro patched its Python in ways that break the app.
- [Dependency cooldown](https://pipx.pypa.io/latest/how-to/dependency-cooldown.html): Skip index artifacts uploaded in the last few days, so a compromised or broken release has time to be caught and yanked before your machine picks it up. Reach for this when you install or upgrade tools from a public index and can afford to lag the newest version.
- [Use a private index](https://pipx.pypa.io/latest/how-to/use-private-index.html): Install from a private index, behind a proxy, or offline by forwarding index options to the backend.
- [Use the uv backend](https://pipx.pypa.io/latest/how-to/use-uv-backend.html): Make pipx use uv to create virtual environments and install packages in place of pip and venv. The CLI surface stays the same.
- [Use with pre-commit](https://pipx.pypa.io/latest/how-to/use-with-pre-commit.html): Run a pipx app as a pre-commit hook. This is useful for apps that work with pipx run but have no native pre-commit support, when you want the prebuilt wheel from PyPI rather than a source build, or when you need pipx’s --spec and --index-url flags.
- [Troubleshoot](https://pipx.pypa.io/latest/how-to/troubleshoot.html): Diagnose and fix common pipx problems, from wrong package versions to broken environments.

## Reference
- [CLI reference](https://pipx.pypa.io/latest/reference/cli.html): -h, --help - show this help message and exit
- [Environment variables](https://pipx.pypa.io/latest/reference/environment-variables.html): pipx has no user configuration file. Every setting is an environment variable, all of them optional. Run pipx environment to print each variable as set in your environment, followed by the values pipx derives from them.
- [Exit codes](https://pipx.pypa.io/latest/reference/exit-codes.html): pipx returns 0 on success and 1 on failure. run, runpip, and exec exit with the code of the app or pip they ran, and argument-parsing errors exit 2. A command that raises an unexpected error or is interrupted also exits non-zero. The named codes below come from pipx.constants; each maps to 0 or 1.
- [JSON output](https://pipx.pypa.io/latest/reference/json-output.html): Most pipx commands accept --output json to print a single machine-readable result envelope on stdout instead of human-readable text. Selecting JSON suppresses pipx’s own progress messages and sends whatever pip or uv print while installing to stderr, so the envelope is the only thing on stdout. When install moves to another Python because the package’s requires-python rules out the default one, pipx says so on stderr as well.
- [On-disk metadata](https://pipx.pypa.io/latest/reference/metadata.html): pipx has no user configuration file. It is configured only through environment variables. The only per-installation state pipx keeps is a metadata file inside each managed virtual environment.
- [Examples](https://pipx.pypa.io/latest/reference/examples.html): Copy-paste command examples. For every flag see the CLI reference. For step-by-step narratives, follow the how-to guides linked in each section.
- [Programs to try](https://pipx.pypa.io/latest/reference/programs-to-try.html): Applications worth trying with pipx run, which fetches the package into a temporary environment and runs it without installing. Add --help on first use so an unfamiliar tool does not act unexpectedly. Swap run for install to keep any of them on your PATH.

## Explanation
- [How pipx works](https://pipx.pypa.io/latest/explanation/how-pipx-works.html): This page describes the pip backend model, where a shared pip environment backs every managed venv through a .pth file. When the uv backend is active (the default whenever uv is available, via the pipx[uv] extra or on PATH) pipx skips the shared environment and uses uv venv and uv pip instead; uv-created venvs ship without pip. See ../how-to/use-uv-backend.
- [Project scope](https://pipx.pypa.io/latest/explanation/scope.html): pipx installs and runs Python applications. It manages the isolated environments that support those applications and exposes their entry points on PATH.
- [Comparisons](https://pipx.pypa.io/latest/explanation/comparisons.html): pip is a general Python package installer. It can install libraries or CLI applications with entry points.
- [Making packages compatible](https://pipx.pypa.io/latest/explanation/making-packages-compatible.html): If you are a developer and want users to be able to run