pipx

library1.11.1pypypiunverified

pipx (Python Package Installer for Executables) is a tool to install and run Python applications in isolated environments. It ensures that executable applications installed via pip do not interfere with your system's global Python environment or other projects. It's currently at version 1.11.1 and follows an active, irregular release cadence, often aligning with important bug fixes or Python version support changes. pipx is primarily a command-line interface tool.

devops http-networking testing

pip install pipx

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PIPX

pipx

devopspythonv1.11.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

This quickstart demonstrates the core workflow of pipx: installing pipx itself, then using it to install a sample CLI application (cowsay), running it, listing installed applications, and finally uninstalling it. All interactions are done by calling pipx as a command-line tool via subprocess, reflecting its primary mode of use.

import subprocess import sys import os # This quickstart demonstrates installing an application via pipx. # pipx is primarily a command-line tool, so interaction is via subprocess calls. # 1. Ensure pipx itself is installed print("Ensuring pipx is installed...") subprocess.run([sys.executable, "-m", "pip", "install", "pipx"], check=True, capture_output=True) print("pipx ensured to be installed.") # 2. Install a sample application (e.g., 'cowsay') app_name = "cowsay" print(f"\nAttempting to install '{app_name}' with pipx...") try: subprocess.run(["pipx", "install", app_name], check=True, capture_output=True) print(f"'{app_name}' installed successfully.") except subprocess.CalledProcessError as e: if "is already installed" in e.stderr.decode(): print(f"'{app_name}' was already installed. Proceeding.") else: print(f"Error installing {app_name}: {e.stderr.decode()}") sys.exit(1) # 3. Run the installed application message = "Hello from checklist.day's pipx quickstart!" print(f"\nRunning '{app_name}' via pipx...") try: # Use 'pipx run' for demonstration, which temporarily adds to PATH # and executes. For persistently installed apps, users would typically # run 'cowsay <message>' directly after 'pipx ensurepath'. result = subprocess.run(["pipx", "run", app_name, message], capture_output=True, text=True, check=True) print(result.stdout) except subprocess.CalledProcessError as e: print(f"Error running {app_name}: {e.stderr.decode()}") sys.exit(1) # 4. List installed applications and uninstall print("\nListing pipx installed applications:") subprocess.run(["pipx", "list"], check=True) print(f"\nUninstalling '{app_name}'...") subprocess.run(["pipx", "uninstall", app_name], check=True, capture_output=True) print(f"'{app_name}' uninstalled successfully.")

pipx --version

Debug

Known issues

breakingAs of pipx version 1.11.0, support for Python versions older than 3.9 has been dropped. If your primary Python environment is older than 3.9, you will need to upgrade Python or use an older pipx version (not recommended for security and features).

fix

Ensure your system's Python is 3.9 or newer before installing/upgrading pipx.

affects: 1.11.0+

gotchaAfter installing pipx itself, or an application with pipx, you often need to run `pipx ensurepath` to add pipx's applications directory to your system's PATH. If you don't, applications installed by pipx might not be directly runnable from your shell until you do so and restart your shell.

fix

Execute `pipx ensurepath` after installation and restart your terminal or shell.

affects: All versions

gotchapipx installs applications into isolated virtual environments, preventing dependency conflicts. This differs from `pip install --user`, which installs into your user's site-packages globally. Consequently, pipx-installed applications are not available in your global Python environment.

fix

Understand that pipx applications live in their own venvs. Use `pipx list` to see them and `pipx run <app>` to execute, or `pipx ensurepath` for direct execution.

affects: All versions

gotchaThe `pipx run <package>` command executes a Python application from a temporary environment and cleans up afterward. Use this for one-off executions. For applications you intend to use repeatedly and have available persistently in your PATH, use `pipx install <package>`.

fix

Choose `pipx install` for persistent applications and `pipx run` for ephemeral, single-use executions.

affects: All versions

Errors

Common errors & fixes

pipx: command not found

The directory where pipx installs its executables (typically `~/.local/bin` on Linux/macOS or `%USERPROFILE%\.local\bin` on Windows) is not included in your system's PATH environment variable, so the shell cannot find the `pipx` command. This can happen if you install `pipx` via `pip install --user pipx` but don't run `pipx ensurepath` or restart your shell.

fix

After installing `pipx`, run `pipx ensurepath` to add the necessary directory to your PATH. You will likely need to restart your terminal or shell session for the changes to take effect. 

For Unix/macOS: `pipx ensurepath`
For Windows PowerShell: `pipx ensurepath` (then restart PowerShell)

Alternatively, if you installed via a system package manager (e.g., `brew install pipx` on macOS, `sudo apt install pipx` on Ubuntu), ensure the package manager's bin directory is in your PATH.

error: externally-managed-environment × This environment is externally managed

This error occurs on Python 3.11+ and certain Linux distributions (e.g., Ubuntu 23.04+, Debian 12+, Fedora 38+) that implement PEP 668, which marks the system Python as 'externally managed'. This prevents `pip` (and sometimes `pipx` when trying to operate on system-wide Python) from installing packages directly into the system's Python environment to avoid breaking system components.

fix

When installing applications, use your distribution's package manager if `pipx` is available (e.g., `sudo apt install pipx`, `sudo dnf install pipx`, `brew install pipx`). If installing `pipx` itself, avoid `pip install --user pipx` and use the system package manager or install `pipx` into its own virtual environment. When using `pipx` to install Python applications, it inherently handles virtual environments for isolation, so this error usually points to an issue with `pipx`'s own installation or a misunderstanding of `pip` vs `pipx` usage.

Fatal error from pip prevented installation. Full pip output in file: .../pip_errors.log

This indicates that an underlying `pip` command, used by `pipx` to install the package within its isolated virtual environment, failed. Common reasons include a Python version upgrade that broke `pipx`'s shared virtual environment, missing build dependencies for the package being installed, or conflicts with `PIP_*` environment variables.

fix

First, check the detailed error log mentioned in the output. Common fixes include: 
1. Reinstalling all `pipx`-managed packages: `pipx reinstall-all`
2. If the issue is related to a Python upgrade, consider removing and reinstalling `pipx` and its shared environment. On Unix/macOS: `rm -rf ~/.local/pipx` then `python3 -m pip install --user pipx && python3 -m pipx ensurepath`.
3. Ensure you have necessary system build tools (e.g., `build-essential` on Debian/Ubuntu, `Xcode Command Line Tools` on macOS).
4. Check for and unset any problematic `PIP_*` environment variables using `env | grep '^PIP_'` (Unix/macOS) or `set PIP_` (Windows cmd).

No apps associated with package <package-name>. Try again with '--include-deps' to include apps of dependent packages, which are listed above. If you are attempting to install a library, pipx should not be used. Consider using pip or a similar tool instead.

`pipx` is designed for installing command-line *applications*, not Python *libraries*. This message appears when the package you are trying to install does not define `console_scripts` entry points, which are how `pipx` identifies executable applications. Alternatively, you might want to install an app provided by one of the package's dependencies.

fix

If the package is truly a library to be imported in your Python code, you should install it with `pip` within a virtual environment (e.g., `python -m venv .venv && source .venv/bin/activate && pip install my-library`). If it is an application and you expect it to have executables but they are from its dependencies, try `pipx install <package-name> --include-deps`. If you are the package author, ensure your `setup.py` or `pyproject.toml` correctly defines `console_scripts` entry points.

Upgrade

Version history

1.11.1latest on PyPI · released Mar 31, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/pypa/pipx ↗

packagehttps://pypi.org/project/pipx/ ↗

homepagehttps://pipx.pypa.io ↗

docshttps://pipx.pypa.io ↗

changeloghttps://pipx.pypa.io/latest/changelog/ ↗