{"id":1629,"library":"pipx","title":"pipx: Install and Run Python Applications in Isolated Environments","description":"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.","status":"active","version":"1.11.1","language":"python","source_language":"en","source_url":"https://github.com/pypa/pipx","tags":["CLI","package manager","environment management","tools","virtual environment"],"install":[{"cmd":"pip install pipx","lang":"bash","label":"Install pipx"}],"dependencies":[],"imports":[],"quickstart":{"code":"import subprocess\nimport sys\nimport os\n\n# This quickstart demonstrates installing an application via pipx.\n# pipx is primarily a command-line tool, so interaction is via subprocess calls.\n\n# 1. Ensure pipx itself is installed\nprint(\"Ensuring pipx is installed...\")\nsubprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"pipx\"], check=True, capture_output=True)\nprint(\"pipx ensured to be installed.\")\n\n# 2. Install a sample application (e.g., 'cowsay')\napp_name = \"cowsay\"\nprint(f\"\\nAttempting to install '{app_name}' with pipx...\")\ntry:\n    subprocess.run([\"pipx\", \"install\", app_name], check=True, capture_output=True)\n    print(f\"'{app_name}' installed successfully.\")\nexcept subprocess.CalledProcessError as e:\n    if \"is already installed\" in e.stderr.decode():\n        print(f\"'{app_name}' was already installed. Proceeding.\")\n    else:\n        print(f\"Error installing {app_name}: {e.stderr.decode()}\")\n        sys.exit(1)\n\n# 3. Run the installed application\nmessage = \"Hello from checklist.day's pipx quickstart!\"\nprint(f\"\\nRunning '{app_name}' via pipx...\")\ntry:\n    # Use 'pipx run' for demonstration, which temporarily adds to PATH\n    # and executes. For persistently installed apps, users would typically\n    # run 'cowsay <message>' directly after 'pipx ensurepath'.\n    result = subprocess.run([\"pipx\", \"run\", app_name, message], capture_output=True, text=True, check=True)\n    print(result.stdout)\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error running {app_name}: {e.stderr.decode()}\")\n    sys.exit(1)\n\n# 4. List installed applications and uninstall\nprint(\"\\nListing pipx installed applications:\")\nsubprocess.run([\"pipx\", \"list\"], check=True)\n\nprint(f\"\\nUninstalling '{app_name}'...\")\nsubprocess.run([\"pipx\", \"uninstall\", app_name], check=True, capture_output=True)\nprint(f\"'{app_name}' uninstalled successfully.\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your system's Python is 3.9 or newer before installing/upgrading pipx.","message":"As 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).","severity":"breaking","affected_versions":"1.11.0+"},{"fix":"Execute `pipx ensurepath` after installation and restart your terminal or shell.","message":"After 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"pipx 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Choose `pipx install` for persistent applications and `pipx run` for ephemeral, single-use executions.","message":"The `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>`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.11.1':54 'activ':58 'align':63 'applic':6,24,32 'bug':66 'cadenc':61 'chang':72 'cli':82 'command':78 'command-lin':77 'current':51 'ensur':29 'environ':9,27,45,85,89 'execut':15,31 'fix':67 'follow':56 'global':43 'import':65 'instal':2,13,20,33 'interfac':80 'interfer':38 'irregular':59 'isol':8,26 'line':79 'manag':84,86 'often':62 'packag':12,83 'pip':35 'pipx':1,10,73 'primarili':75 'project':48 'python':5,11,23,44,69 'releas':60 'run':4,22 'support':71 'system':41 'tool':18,81,87 'version':53,70 'via':34 'virtual':88","created_at":"2026-04-09T03:56:19.728619+00:00","updated_at":"2026-04-16T18:02:48.576766+00:00","problems":[{"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. \n\nFor Unix/macOS: `pipx ensurepath`\nFor Windows PowerShell: `pipx ensurepath` (then restart PowerShell)\n\nAlternatively, 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.","cause":"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.","error":"pipx: command not found"},{"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.","cause":"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.","error":"error: externally-managed-environment\n× This environment is externally managed"},{"fix":"First, check the detailed error log mentioned in the output. Common fixes include: \n1. Reinstalling all `pipx`-managed packages: `pipx reinstall-all`\n2. 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`.\n3. Ensure you have necessary system build tools (e.g., `build-essential` on Debian/Ubuntu, `Xcode Command Line Tools` on macOS).\n4. Check for and unset any problematic `PIP_*` environment variables using `env | grep '^PIP_'` (Unix/macOS) or `set PIP_` (Windows cmd).","cause":"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.","error":"Fatal error from pip prevented installation. Full pip output in file: .../pip_errors.log"},{"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.","cause":"`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.","error":"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."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"pipx","cli_version":"1.12.0","type":"library","homepage":"https://pipx.pypa.io","github":"https://github.com/pypa/pipx","docs":"https://pipx.pypa.io","changelog":"https://pipx.pypa.io/latest/changelog/","pypi":"https://pypi.org/project/pipx/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","http-networking","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-09","next_check":"2026-07-08","install_tag":null}}