Skip to content


pipx install examples

pipx install pycowsay
pipx install --python python3.10 pycowsay
pipx install --python 3.12 pycowsay
pipx install --fetch-missing-python --python 3.12 pycowsay
pipx install git+
pipx install git+
pipx install git+
pipx install git+ssh://<username>@<private-repo-domain>/<path-to-package.git>
pipx install
pipx install black[d]
pipx install 'black[d] @ git+'
pipx install --suffix @branch-name 'black[d] @ git+'
pipx install --include-deps jupyter
pipx install --pip-args='--pre' poetry
pipx install --pip-args='--index-url=<private-repo-host>:<private-repo-port> --trusted-host=<private-repo-host>:<private-repo-port>' private-repo-package
pipx install --index-url --pip-args='--extra-index-url' some-package
pipx --global install pycowsay
pipx install .
pipx install path/to/some-project

pipx run examples

pipx enables you to test various combinations of Python versions and package versions in ephemeral environments:

pipx run BINARY  # latest version of binary is run with python3
pipx run --spec PACKAGE==2.0.0 BINARY  # specific version of package is run
pipx run --python python3.7 BINARY  # Installed and invoked with specific Python version
pipx run --python python3.9 --spec PACKAGE=1.7.3 BINARY
pipx run --spec git+https://url.git BINARY  # latest version on default branch is run
pipx run --spec git+https://url.git@branch BINARY
pipx run --spec git+https://url.git@hash BINARY
pipx run pycowsay moo
pipx --version  # prints pipx version
pipx run pycowsay --version  # prints pycowsay version
pipx run --python pythonX pycowsay
pipx run pycowsay==2.0 --version
pipx run pycowsay[dev] --version
pipx run --spec git+ black
pipx run --spec git+ black
pipx run --spec git+ black
pipx run --spec black --help
pipx run

You can run local files, or scripts hosted on the internet, and you can run them with arguments:

pipx run
pipx run 1 2 3
pipx run
pipx run 1 2 3

A simple filename is ambiguous - it could be a file, or a package on PyPI. It will be treated as a filename if the file exists, or as a package if not. To force interpretation as a local path, use --path, and to force interpretation as a package name, use --spec (with the PyPI name of the package).

pipx run # Local file, if exists
pipx run # Package, because is not a local file
pipx run --path # Always a local file
pipx run --spec test-py # Always a package on PyPI

You can also run scripts that have dependencies:

If you have a script that needs 3rd party libraries, you can add inline script metadata in the style of PEP 723.


# /// script
# dependencies = ["requests"]
# ///

import sys
import requests
project = sys.argv[1]
pipx_data = requests.get(f"{project}/json").json()

Then you can run it as follows:

> pipx run pipx

pipx inject example

One use of the inject command is setting up a REPL with some useful extra packages.

pipx install ptpython
pipx inject ptpython requests pendulum

After running the above commands, you will be able to import and use the requests and pendulum packages inside a ptpython repl.

pipx list example

> pipx list
venvs are in /Users/user/.local/pipx/venvs
binaries are exposed on your $PATH at /Users/user/.local/bin
   package black 18.9b0, Python 3.7.0
    - black
    - blackd
   package pipx 0.10.0, Python 3.7.0
    - pipx

> pipx list --short
black 18.9b0
pipx 0.10.0