Examples

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.

install

Install from PyPI, optionally pinning the Python version:

pipx install pycowsay
pipx install --python 3.12 pycowsay
pipx install --fetch-python=missing --python 3.12 pycowsay

Constrain or eagerly upgrade a version spec:

pipx install --upgrade 'black>=22,<23'
pipx install --upgrade --upgrade-strategy eager 'black>=22,<23'

Install extras, include dependency apps, or preinstall build-time packages:

pipx install 'black[d]'
pipx install --include-deps jupyter
pipx install --preinstall ansible-lint --preinstall mitogen ansible-core

Install from a VCS URL, an archive, or a local project:

pipx install git+https://github.com/psf/black
pipx install git+https://github.com/psf/black.git@branch-name
pipx install https://github.com/psf/black/archive/18.9b0.zip
pipx install ./path/to/some-project

Install from a PEP 723 script or a lock file:

pipx install ./script.py
pipx install --lock pylock.toml .

For a local script, the filename without its extension supplies the command name. A script without the .py extension needs a path such as ./script; a bare script names the package on the index. Pass --app to choose a different name:

pipx install --app greet ./script.py

Pass arguments through to pip, or install globally for all users:

pipx install --pip-args='--pre' poetry
pipx install --global pycowsay

run

Run an app in a temporary environment, optionally pinning package or Python version:

pipx run pycowsay moo
pipx run --spec 'pycowsay==0.0.0.2' pycowsay --version
pipx run --python 3.12 pycowsay moo

Run from a VCS URL or an archive:

pipx run git+https://github.com/psf/black.git
pipx run --spec https://github.com/psf/black/archive/18.9b0.zip black --help

Run a local or remote script, with arguments:

pipx run test.py 1 2 3
pipx run https://example.com/test.py 1 2 3

A bare filename is ambiguous: pipx runs it as a local file when the file exists, otherwise as a PyPI package. Force the interpretation with --path or --spec:

pipx run --path test.py         # always a local file
pipx run --spec test-py test.py # always a PyPI package

A requirement with a version, extras, an environment marker or a direct URL always selects the package, even when the working directory contains a file with the same name. Use --path or an explicit relative path to run such a file.

Scripts can declare dependencies with PEP 723 inline metadata; pipx installs them into the temporary environment. See Run scripts.

inject

Add packages to an existing environment, from the command line or a requirements file:

pipx inject ptpython requests pendulum
pipx inject ptpython --requirement useful-packages.txt

You can combine and repeat the two forms:

pipx inject ptpython package-1 package-2 -r extra-1.txt -r extra-2.txt

See Inject packages for the requirements-file format and the --include-apps option.

list

List installed packages and their apps:

$ pipx list
venvs are in /home/user/.local/share/pipx/venvs
apps are exposed on your $PATH at /home/user/.local/bin
manual pages are exposed at /home/user/.local/share/man
shell completions are exposed at /home/user/.local/share
   package black 24.3.0, installed using Python 3.12.0
    - black
    - blackd
   package pipx 1.4.3, installed using Python 3.12.0
    - pipx

Narrow the output or change the format; the package filter works with every format:

pipx list --short
pipx list black pipx --short
pipx list black --outdated
pipx list --output json > pipx.json

install-all

Reinstall from a snapshot produced by pipx list --output json (see JSON output). Each environment gets the interpreter, venv and pip arguments the snapshot recorded unless you pass your own. A --backend other than the recorded one skips the recorded pip arguments with a warning, since they can hold options only the old backend accepts. pipx translates options with an exact equivalent instead, so the environment still installs from the recorded index:

pip	uv
--index-url, -i	--default-index
--extra-index-url	--index (pipx drops a name= prefix for pip)
--find-links, -f	--find-links (split on commas for pip)
--no-index	--no-index
--pre	--prerelease allow
--trusted-host HOST	--allow-insecure-host HOST
--constraint, -c	--constraints
--keyring-provider	--keyring-provider (disabled or subprocess)
(always picks the best match)	--index-strategy unsafe-best-match

pipx translates a pip option recorded as an abbreviation pip accepts, such as --index-u, like its full spelling. When a recorded index option has no equivalent, such as a uv --index-strategy other than unsafe-best-match, an --allow-insecure-host URL, or pip’s --keyring-provider import, pipx refuses to install that environment rather than fall back to PyPI.

pip searches every index for the best version, while uv stops at the first index that has the package, so a uv --index moved to pip can pick a newer release from PyPI. Pass --pip-args to replace the recorded options.

pipx skips the recorded interpreter, says why, and uses the default Python when that interpreter is gone, sits inside a virtual environment, or, on Unix, can be changed by another account through the file or a directory above it. Pass --python to pick one yourself.

Up to eight environments install at once, with their output printed in snapshot order:

$ pipx install-all pipx.json
'black' (24.3.0) is already installed. Not
modifying existing installation in '/home/user/.local/share/pipx/venvs/black'.
Pass '--force' to force installation, or use
'pipx upgrade black' to upgrade.
'pipx' (1.4.3) is already installed. Not
modifying existing installation in '/home/user/.local/share/pipx/venvs/pipx'.
Pass '--force' to force installation, or use
'pipx upgrade pipx' to upgrade.
$ pipx install-all pipx.json --force
Installing to existing venv 'black'
  installed package black 24.3.0, installed using Python 3.12.0
  These apps are now available
    - black
    - blackd
Installing to existing venv 'pipx'
  installed package pipx 1.4.3, installed using Python 3.12.0
  These apps are now available
    - pipx

upgrade-shared

Upgrade the shared libraries now, instead of waiting for the automatic refresh once they are more than 30 days old:

pipx upgrade-shared

pin

Pin an environment so pipx holds its packages at their current versions until you unpin. See Pin packages.

Pin only injected packages, leaving the main package upgradable:

$ pipx pin poetry --injected-only
pipx pinned 2 packages in venv poetry
  - poetry-plugin-export <current version>
  - poetry-plugin-app <current version>

Unpin the environment so upgrades resume. The output lists only the packages that were pinned:

$ pipx unpin poetry
pipx unpinned 2 packages in venv poetry
  - poetry-plugin-export
  - poetry-plugin-app