pip-run (2024)

Module Script Runner

Perhaps the most powerful usage of pip-run is its ability to invokeexecutable modules and packages viarunpy (akapython -m):

$ pip-run cowsay -- -m cowsay "moove over, pip-run" -------------------< moove over, pip-run > ------------------- \ ^__^ \ (oo)\_______ (__)\ )\/\ ||----w | || ||

Module Executable Runner

Some package tools, like ranger, areinvoked with a unique executable instead of a module. pip-run canrun an executable from a package if it is prependend by a !:

$ pip-run ranger-fm -- '!ranger'

Command Runner

Note that everything after the – is passed to the python invocation,so it’s possible to have a one-liner that runs under a dependencycontext:

$ python -m pip-run requests -- -c "import requests; print(requests.get('https://pypi.org/project/pip-run').status_code)"200

As long as pip-run is installed in each of Python environmentson the system, this command can be readily repeated on the otherpython environments by specifying the relevant interpreter:

$ py -3.7 -m pip-run ...

Script Runner

pip-run can run a Python file with indicated dependencies. Becausearguments after -- are passed directly to the Python interpreterand because the Python interpreter will run any script, invoking a scriptwith dependencies is easy. Consider this script “myscript.py”:

#!/usr/bin/env pythonimport requestsreq = requests.get('https://pypi.org/project/pip-run')print(req.status_code)

To invoke it while making sure requests is present:

$ pip-run requests – myscript.py

pip-run will make sure that requests is installed then invokethe script in a Python interpreter configured with requests and itsdependencies.

For added convenience when running scripts, pip-run will inferthe beginning of Python parameters if it encounters a filenameof a Python script that exists, allowing for omission of the --for script invocation:

$ pip-run requests myscript.py

Script-declared Dependencies

Building on Script Runner above, pip-run also allowsdependencies to be declared in the script itself so thatthe user need not specify them at each invocation.

To declare dependencies in a script, add a __requires__variable or # Requirements: section to the script:

#!/usr/bin/env python__requires__ = ['requests']# or (PEP 723)# /// script# dependencies = ['requests']# ///import requestsreq = requests.get('https://pypi.org/project/pip-run')print(req.status_code)

With that declaration in place, one can now invoke pip-run withoutdeclaring any parameters to pip:

$ pip-run myscript.py200

The format for requirements must follow PEP 508.

Single-script Tools and Shebang Support

Combined with in-script dependencies, pip-run can be used as a shebang tocreate fully self-contained scripts that install and run their owndependencies, as long as pip-run is installed on the system PATH.Consider, for example, the pydragon script:

#!/usr/bin/env pip-run__requires__ = ['requests', 'beautifulsoup4', 'cowsay']import requestsfrom bs4 import BeautifulSoup as BSimport cowsayres = requests.get('https://python.org')b = BS(res.text, 'html.parser')cowsay.dragon(b.find("div", class_="introduction").get_text())

This executable script is available in the repo as examples/pydragon (forUnix) and examples/pydragon.py (for Windows [2]). Executing this script isequivalent to executing pip-run pydragon.

By default, the script will assemble the dependencies on each invocation,which may be inconvenient for a script. See Environment Persistence for a technique to persist the assembleddependencies across invocations. One may inject PIP_RUN_MODE=persistin the shebang, but be aware that doing so breaks Windows portability.

Other Script Directives

pip-run also recognizes a global __index_url__ attribute. If present,this value will supply --index-url to pip with the attribute value,allowing a script to specify a custom package index:

#!/usr/bin/env python__requires__ = ['my_private_package']__index_url__ = 'https://my.private.index/'import my_private_package...

Extracting Requirements

After having used pip-run to run scripts, it may be desirable to extract the requirements from the __requires__ variable or # Requirements: section of ascript to install those more permanently. pip-run provides a routine to facilitatethis case:

$ py -m pip_run.read-deps examples/pydragonrequests beautifulsoup4 cowsay

On Unix, it is possible to pipe this result directly to pip:

$ pip install $(py -m pip_run.read-deps examples/pydragon)

To generate a requirements.txt file, specify a newline separator:

$ py -m pip_run.read-deps --separator newline examples/pydragon > requirements.txt

And since pipenv uses the same syntax,the same technique works for pipenv:

$ pipenv install $(python -m pip_run.read-deps script.py)

Interactive Interpreter

pip-run also offers a painless way to run a Python interactiveinterpreter in the context of certain dependencies:

$ /clean-install/python -m pip-run boto>>> import boto>>>

Experiments and Testing

Because pip-run provides a single-command invocation, itis great for experiments and rapid testing of various packagespecifications.

Consider a scenario in which one wishes to create an environmentwhere two different versions of the same package are installed,such as to replicate a broken real-world environment. Stack twoinvocations of pip-run to get two different versions installed:

$ pip-run keyring==21.8.0 -- -m pip-run keyring==22.0.0 -- -c "import importlib.metadata, pprint; pprint.pprint([dist._path for dist in importlib.metadata.distributions() if dist.metadata['name'] == 'keyring'])"[PosixPath('/var/folders/03/7l0ffypn50b83bp0bt07xcch00n8zm/T/pip-run-a3xvd267/keyring-22.0.0.dist-info'),PosixPath('/var/folders/03/7l0ffypn50b83bp0bt07xcch00n8zm/T/pip-run-1fdjsgfs/keyring-21.8.0.dist-info')]

IPython Inference

If IPython is specified as one of the dependencies, the Pythoninterpreter will be launched via IPython (using -m IPython)for interactive mode. This behaviour may be toggled off bysetting the environment variable PIP_RUN_IPYTHON_MODE=ignore.