Package: pip-run
pip-runprovides on-demand temporary package installation
for a single execution run.It replaces this series of commands (or their Windows equivalent):$ virtualenv --python pythonX.X --system-site-packages $temp/env
$ $temp/env/bin/pip install pkg1 pkg2 -r reqs.txt
$ $temp/env/bin/python ...
$ rm -rf $temp/envWith this single-line command:$ py -X.X -m pip-run pkg1 pkg2 -r reqs.txt -- ...Notepyis the Python Launcher forWindowsorUnixand isn’t required to use
pip-run, but is used in this guide and recommended for anyone to get
a portable, cruft-free Python invocation.Features includeDownloads missing dependencies and makes their packages available for import.Installs packages to a special staging location such that they’re not installed after the process exits.Relies on pip to cache downloads of such packages for reuse.Leaves no trace of its invocation (except files in pip’s cache).Supersedes installed packages when required.Relies on packages already satisfied[1].Re-uses the pip tool chain for package installation.pip-runis not intended to solve production dependency management, but does aim to address the other, one-off scenarios around dependency management:trials and experimentsbuild setuptest runnersjust in time script runninginteractive developmentbug triagepip-runis a complement to Pip and Virtualenv, intended to more
readily address the on-demand needs.[1]Except when a requirements file is used.Installationpip-runis meant to be installed in the system site packages
alongside pip, though it can also be installed in a virtualenv.Usageas script launcheras runtime dependency context manageras interactive interpreter in dependency contextas module launcher (akin topython -m)as a shell shebang (#!/usr/bin/envpip-run), to create single-file Python toolsInvokepip-runfrom the command-line using the console entry
script (simplypip-run) or using the module executable (python-mpip-run). This latter usage is particularly convenient
for testing a command across various Python versions.Parameters following pip-run are passed directly topip install,
sopip-runnumpywill installnumpy(reporting any work done
during the install) andpip-run-v-rrequirements.txtwill verbosely
install all the requirements listed in a file called requirements.txt
(quiet is the default).
Anyenvironment variables honored by pipare also honored.Following the parameters topip install, one may optionally
include a--after which any parameters will be executed
by a Python interpreter in the context or directly if prefixed by!.Seepip-run--helpfor more details.ExamplesTheexamples folder in this projectincludes some examples demonstrating
the power and usefulness of the project. Read the docs on those examples
for instructions.Module Script RunnerPerhaps the most powerful usage ofpip-runis its ability to invoke
executable modules and packages viarunpy(akapython-m):$ pip-run cowsay -- -m cowsay "moove over, pip-run"

  -------------------
< moove over, pip-run >
  -------------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||Module Executable RunnerSome package tools, likeranger, are
invoked with a unique executable instead of a module.pip-runcan
run an executable from a package if it is prependend by a!:$ pip-run ranger-fm -- '!ranger'Command RunnerNote that everything after the – is passed to the python invocation,
so it’s possible to have a one-liner that runs under a dependency
context:$ python -m pip-run requests -- -c "import requests; print(requests.get('https://pypi.org/project/pip-run').status_code)"
200As long aspip-runis installed in each of Python environments
on the system, this command can be readily repeated on the other
python environments by specifying the relevant interpreter:$ py -3.7 -m pip-run ...Script Runnerpip-runcan run a Python file with indicated dependencies. Because
arguments after--are passed directly to the Python interpreter
and because the Python interpreter will run any script, invoking a script
with dependencies is easy. Consider this script “myscript.py”:#!/usr/bin/env pythonimportrequestsreq=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.pypip-runwill make sure that requests is installed then invoke
the script in a Python interpreter configured with requests and its
dependencies.For added convenience when running scripts,pip-runwill infer
the beginning of Python parameters if it encounters a filename
of a Python script that exists, allowing for omission of the--for script invocation:$ pip-run requests myscript.pyScript-declared DependenciesBuilding on Script Runner above,pip-runalso allows
dependencies to be declared in the script itself so that
the 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']# ///importrequestsreq=requests.get('https://pypi.org/project/pip-run')print(req.status_code)With that declaration in place, one can now invokepip-runwithout
declaring any parameters to pip:$ pip-run myscript.py
200The format for requirements must followPEP 508.Single-script Tools and Shebang SupportCombined with in-script dependencies,pip-runcan be used as a shebang to
create fully self-contained scripts that install and run their own
dependencies, as long aspip-runis installed on the systemPATH.
Consider, for example, thepydragonscript:#!/usr/bin/env pip-run__requires__=['requests','beautifulsoup4','cowsay']importrequestsfrombs4importBeautifulSoupasBSimportcowsayres=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 asexamples/pydragon(for
Unix) andexamples/pydragon.py(for Windows[2]). Executing this script is
equivalent to executingpip-runpydragon.By default, the script will assemble the dependencies on each invocation,
which may be inconvenient for a script. SeeEnvironment Persistencefor a technique to persist the assembled
dependencies across invocations. One may injectPIP_RUN_MODE=persistin the shebang, but be aware that doing so breaks Windows portability.[2].PYmust exist in the PATHEXT for Python scripts to be executable. Seethis documentationfor more background.Other Script Directivespip-runalso recognizes a global__index_url__attribute. If present,
this value will supply--index-urlto 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/'importmy_private_package...Extracting RequirementsAfter having usedpip-runto run scripts, it may be desirable to extract the requirements from the__requires__variable or# Requirements:section of a
script to install those more permanently. pip-run provides a routine to facilitate
this case:$ py -m pip_run.read-deps examples/pydragon
requests beautifulsoup4 cowsayOn 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.txtAnd sincepipenvuses the same syntax,
the same technique works for pipenv:$ pipenv install $(python -m pip_run.read-deps script.py)Interactive Interpreterpip-runalso offers a painless way to run a Python interactive
interpreter in the context of certain dependencies:$ /clean-install/python -m pip-run boto
>>> import boto
>>>Experiments and TestingBecausepip-runprovides a single-command invocation, it
is great for experiments and rapid testing of various package
specifications.Consider a scenario in which one wishes to create an environment
where two different versions of the same package are installed,
such as to replicate a broken real-world environment. Stack two
invocations 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 InferenceIf IPython is specified as one of the dependencies, the Python
interpreter will be launched via IPython (using-mIPython)
for interactive mode. This behaviour may be toggled off by
setting the environment variablePIP_RUN_IPYTHON_MODE=ignore.How Does It Workpip-runeffectively does the following:pip install-t$TMPDIRPYTHONPATH=$TMPDIRpythoncleanupFor specifics, seepip_run.run().Environment Persistencepip-runhonors thePIP_RUN_RETENTION_STRATEGYvariable. If unset or
set todestroy, dependencies are installed to a temporary directory on
each invocation (and deleted after). Setting this variable topersistwill
instead create or re-use a directory in the user’s cache, only installing the
dependencies if the directory doesn’t already exist. A separate cache is
maintained for each combination of requirements specified.persiststrategy can greatly improve startup performance at the expense of
staleness and accumulated cruft.WithoutPIP_RUN_RETENTION_STRATEGY=persist(or with=destroy),pip-runwill re-install dependencies every time a script runs, silently
adding to the startup time while dependencies are installed into an ephemeral
environment, depending on how many dependencies there are and whether the
dependencies have been previously downloaded to the local pip cache. Usepip-run-v...to see the installation activity.The location of the cache can be revealed with this command:py -c 'import importlib; print(importlib.import_module("pip_run.retention.persist").paths.user_cache_path)'LimitationsDue to limitations withpip,pip-runcannot run with “editable”
(-e) requirements.pip-runuses asitecustomizemodule to ensure that.pthfiles
in the requirements are installed. As a result, any environment
that has asitecustomizemodule will find that module masked
when running underpip-run.Comparison with pipxThepipx projectis another mature
project with similar goals. Both projects expose a project and its
dependencies in ephemeral environments. The main difference is pipx
primarily exposes Python binaries (console scripts) from those
environments whereas pip-run exposes a Python context (including
runpy scripts).Featurepip-runpipxuser-mode operation✓✓invoke console scripts✓✓invoke runpy modules✓run standalone scripts✓interactive interpreter with deps✓re-use existing environment✓ephemeral environments✓✓persistent environments✓✓PEP 582 support✓Specify optional dependencies✓Python 2 support✓Comparison with virtualenvwrapper mktmpenvThevirtualenvwrapper projectattempts to address some of the use-cases that pip-run solves,
especially with themktmpenvcommand, which destroys the
virtualenv after deactivation. The main difference is thatpip-runis transient only for the invocation of a single command, whilemktmpenvlasts for a session.Featurepip-runmktmpenvcreate temporary package environment✓✓re-usable across python invocations✓✓portable✓one-line invocation✓multiple interpreters in session✓run standalone scripts✓✓interactive interpreter with deps✓✓re-use existing environment✓ephemeral environments✓✓persistent environments✓✓IntegrationThe author created this package with the intention of demonstrating
the capability before integrating it directly with pip in a command
such aspip run. After proposing the change, the idea was largely
rejected inpip 3971.If you would like to see this functionality made available in pip,
please upvote or comment in that ticket.Versioningpip-runuses semver, so you can use this library with
confidence about the stability of the interface, even
during periods of great flux.TestingInvoke tests withtox.For EnterpriseAvailable as part of the Tidelift Subscription.This project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.Learn more.