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 .

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==2.0' 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

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

The two forms can be combined and repeated:

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

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
   package black 24.3.0, Python 3.12.0
    - black
    - blackd
   package pipx 1.4.3, 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):

$ pipx install-all pipx.json
'black' already seems to be installed. Not modifying existing installation in '/usr/local/pipx/venvs/black'. Pass '--force' to force installation.
'pipx' already seems to be installed. Not modifying existing installation in '/usr/local/pipx/venvs/pipx'. Pass '--force' to force installation.
$ 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 globally available
    - black
    - blackd
Installing to existing venv 'pipx'
  installed package pipx 1.4.3, installed using Python 3.12.0
  These apps are now globally available
    - pipx

upgrade-shared

Upgrade the shared libraries, or pin pip to a specific version until the next automatic upgrade:

pipx upgrade-shared
pipx upgrade-shared --pip-args=pip==24.0

pin

Pin an environment so its packages are held at their current versions until you unpin. See Pin packages.

Pin only injected packages, leaving the main package upgradable:

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

Unpin the whole environment so upgrades resume:

$ pipx unpin poetry
Unpinned 3 packages in venv poetry
  - poetry
  - poetry-plugin-export
  - poetry-plugin-app