Running applications

pipx run downloads and runs a Python application in a one-time, temporary environment, then leaves your system untouched. Reach for it to scaffold a new project, check an app’s help text, or try a tool without committing to an install.

Basic usage

$ pipx run pycowsay moo

pipx installs the package in an isolated, temporary directory and invokes the app:

$ pipx run pycowsay moo
  ---
< moo >
  ---
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

Arguments after the app name pass straight through to it:

$ pipx run pycowsay these arguments all go to pycowsay

Ambiguous arguments

pipx can swallow an argument meant for the app when it looks like one of pipx’s own options:

$ pipx run pycowsay --py
pipx run: error: ambiguous option: --py could match --python-args, --pypackages, --python

Put -- before the app name to forward everything after it verbatim:

$ pipx run -- pycowsay --py

When the app name differs

Some packages expose an app under a different name, or expose several. Use --spec to name the package and the app separately:

$ pipx run --spec PACKAGE APP

esptool, for example, lists its executables when you guess wrong:

$ pipx run esptool
'esptool' executable script not found in package 'esptool'.
Available executable scripts:
    esptool.py - usage: 'pipx run --spec esptool esptool.py [arguments?]'
    espefuse.py - usage: 'pipx run --spec esptool espefuse.py [arguments?]'

Run the one you want with --spec:

$ pipx run --spec esptool esptool.py

Package authors can remove this requirement by declaring a pipx.run entry point in their metadata.

Run cache

pipx caches each pipx run environment for a few days so repeated runs start instantly. After the cache expires, the next run fetches the latest version.

        flowchart LR
    RUN["pipx run APP"] --> CHECK{"cached?"}
    CHECK -->|"no"| FETCH["fetch + build venv"]
    FETCH --> CACHE["cache venv"]
    CHECK -->|"yes"| REUSE["reuse cached venv"]
    CACHE --> REUSE
    REUSE --> EXPIRE["expires after a few days"]
    EXPIRE --> RUN

    classDef step fill:#2a9d8f,stroke:#1f7268,color:#fff;
    classDef decide fill:#c78c20,stroke:#946716,color:#fff;
    class RUN,FETCH,CACHE,REUSE,EXPIRE step;
    class CHECK decide;

Force a rebuild before the cache expires with --refresh, which replaces that app’s cached environment and keeps the replacement:

$ pipx run --refresh APP

--no-cache also rebuilds, but marks the new environment for cleanup by a later run. The two options are mutually exclusive.

Inspect or clear every cached run environment:

$ pipx cache dir
$ pipx cache purge

For how pipx decides what to cache and when, see How pipx works.

Learn more