Run Scripts

Running a specific version of a package

The PACKAGE argument is a requirement specifier, so you can pin versions, ranges, or extras:

pipx run mpremote==1.20.0
pipx run --spec esptool==4.6.2 esptool.py
pipx run --spec 'esptool>=4.5' esptool.py

Requirement specifiers containing >, <, or spaces need quoting.

Running with extra dependencies

--with adds packages to the temporary environment alongside the main app:

pipx run --with requests --with rich my-script.py

Running from source control

pipx run accepts git URLs through --spec. Using black as an example:

pipx run --spec git+https://github.com/psf/black.git black
pipx run --spec git+ssh://git@github.com/psf/black black
pipx run --spec git+https://github.com/psf/black.git@branch black
pipx run --spec git+https://github.com/psf/black.git@ce14fa8b497bae2b50ec48b3bd7022573a59cdb1 black
pipx run --spec https://github.com/psf/black/archive/18.9b0.zip black

Running from URL

You can run .py files hosted anywhere:

pipx run https://gist.githubusercontent.com/cs01/fa721a17a326e551ede048c5088f9e0f/raw/6bdfbb6e9c1132b1c38fdd2f195d4a24c540c324/pipx-demo.py

Running scripts with dependencies (PEP 723)

Scripts can declare their own dependencies using inline script metadata. pipx reads the # /// script block and installs the listed packages before running:

# test.py

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

import sys
import requests
project = sys.argv[1]
data = requests.get(f"https://pypi.org/pypi/{project}/json").json()
print(data["info"]["version"])

> pipx run test.py pipx
1.9.0

pipx creates a cached virtual environment keyed to the script's dependency list. Changing the dependencies creates a fresh environment.