pipx: Install and Run Python Applications in Isolated Environments

Warnings

• breaking 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).
  Fix: Ensure your system's Python is 3.9 or newer before installing/upgrading pipx.
• gotcha 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.
  Fix: Execute `pipx ensurepath` after installation and restart your terminal or shell.
• gotcha 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.
  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.
• gotcha 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>`.
  Fix: Choose `pipx install` for persistent applications and `pipx run` for ephemeral, single-use executions.

Install

• pip install pipx Install pipx

Quickstart

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.")