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

On Python 3.11, 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

Under the pip backend, pipx lists the executables of a package when you guess wrong. esptool 4.6.2 ships no esptool script:

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

Run the one you want with --spec:

$ pipx run --spec esptool==4.6.2 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 14 days so repeated runs skip the install. After the cache expires, the next run fetches the latest version. Under the uv backend pipx hands the run to uv tool run, so uv’s own cache applies instead.

        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 14 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 under the pip backend marks the new environment for cleanup by a later run. The two options are mutually exclusive.

Show the cache directory or remove pipx’s cached run environments:

$ pipx cache dir
$ pipx cache purge

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

Learn more