Skip to content

Run Applications

Running an Application in a Temporary Virtual Environment

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

The blog post How to set up a perfect Python project uses pipx run to kickstart a new project with cookiecutter.

pipx run APP [ARGS...]

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

> pipx run pycowsay moo

  ---
< moo >
  ---
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

Arguments after the application name pass straight through:

> pipx run pycowsay these arguments are all passed to pycowsay!

  -------------------------------------------
< these arguments are all passed to pycowsay! >
  -------------------------------------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

pipx caches virtual environments per app for a few days. After they expire, pipx fetches the latest version.

Ambiguous arguments

pipx can consume arguments meant for the application:

> pipx run pycowsay --py

usage: pipx run [-h] [--no-cache] [--pypackages] [--spec SPEC] [--verbose] [--python PYTHON]
                [--system-site-packages] [--index-url INDEX_URL] [--editable] [--pip-args PIP_ARGS]
                app ...
pipx run: error: ambiguous option: --py could match --pypackages, --python

Place -- before the app name to forward all arguments verbatim:

> pipx run -- pycowsay --py


  ----
< --py >
  ----
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

App name differs from package name

Use --spec to specify the package and provide the app name separately:

pipx run --spec PACKAGE APP

The esptool package, for example, exposes executables with different names:

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

Run them with --spec:

pipx run --spec esptool esptool.py

The .py is part of the executable name as declared by the package. The pymodbus package shows a similar pattern:

pipx run --spec pymodbus[repl] pymodbus.console
pipx run --spec pymodbus[repl] pymodbus.server
pipx run --spec pymodbus[repl] pymodbus.simulator

Package authors can avoid this --spec requirement by declaring a pipx.run entry point in their package metadata.