Skip to main content

Adds Python's bin/Scripts directory to PATH before executing a command. Primarily used with Python virtual environments.

Project description


Adds Python’s bin/Scripts directory to PATH before executing a command. Primarily used with Python virtual environments.


A small Python helper tool that will modify the PATH in the environment before executing the executable provided as the first argument. This is useful when programs expect certain binaries to be available in PATH so they can execute them using os.popen() and friends or even for shell scripts that are executing Python tools that one would prefer to not globally install.

Scripts may detect that vrun has been used by looking for the environment variable VRUN_ACTIVATED which is set to 1 when run. It is not recommended that script writers do this.


On macOS/FreeBSD/Linux/Unix:

$ python3 -mvenv ./env/
$ ./env/bin/pip install vrun
$ ./env/bin/vrun /bin/bash -c 'echo $PATH'

On Windows:

C:\> python3.exe -mvenv env
C:\> env\Scripts\pip.exe install vrun
C:\> env\Scripts\vrun.exe python -c "import os; print(os.environ['PATH'])"

If for example there is a script that executes pip without explicitly providing a PATH that includes a virtual environment the system installed pip may accidentally be invoked instead. With vrun the virtual environment will come first in the search path and thus pip will be safely executed within the context of the virtual environment.

Such as a shell script:

$ ./env/bin/vrun ./

Or executing a Windows batch script:

C:\> env\Scripts\vrun.exe script.bat

Command aliases

vrun allows you to define command aliases in a configuration file, either vrun.cfg, vrun.ini or setup.cfg.

These configuration files must contain at least a vrun section, then using standard ini format you may specify key/value pairs:

python.version = python --version
shell = /bin/bash
echo = /bin/bash -c 'echo ${@}' _ {posargs} echo off the bare walls

Now you may run these commands using:

vrun python.version

Which will return something similar to:

Python 3.6.2

Then you can do positional argument interpolation:

vrun echo the soft voices

will output:

the soft voices echo off the bare walls


So long as the keyword {posargs} is stand-alone, and surrounded by spaces (and not inside of a quoted segment) vrun will replace it with any positonal arguments provided on the command line. If not positional arguments are provided, it will remove the {posargs} placeholder and remove it as an argument.

If there is no {posargs} provided in the command alias, all extra arguments provided after the initial command will be passed as positional arguments.

Using the shell example from above, you may do:

vrun shell -c 'echo $PATH'

which will execute:

/bin/bash -c 'echo $PATH'

Within the virtual environment as expected. This can be useful to allow you to predefine certain longer commands, but still allow the user on the fly on the command line to add additional parameters as necessary.

vrun or vexec

vrun installs itself as both vrun and vexec. The later may be typed with the left hand only and is slightly faster to roll off the keyboard!


Please see the LICENSE file in the source code repository

0.4 (2017-09-27)

  • You may now create command aliases by creating a new configuration file named vrun.cfg or adding a section to an existing setup.cfg named [vrun].

    python.version = python --version
    shell = /bin/bash
    echo = /bin/bash -c 'echo ${@}' _ {posargs} echo off the bare walls

    Which may then be used like so:

    vrun python.version
    vrun echo the soft voices
    vrun shell -c 'echo $PATH'
  • New tests have been added, and coverage is now 100%. All new features from now on will have to meet the same coverage requirements to verify there are no breaking changes.

0.3 (2017-06-13)

  • Adds Windows support, so now you can use:

    Script\vrun.exe python -c "import os; print(os.environ['PATH'])"

    To run Windows binaries with their %PATH% modified.

    vrun will also automatically add the .exe when passing the name of a script that exists in the Scripts folder.

    So the following are the same:

    Script\vrun.exe python


    Script\vrun.exe python.exe

0.2 (2017-06-08)

  • Also export the environment variable VIRTUAL_ENV pointing to the virtual environment.

0.1 (2017-06-08)

  • Initial release and implementation of the vrun functionality

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vrun-0.4.tar.gz (11.0 kB view hashes)

Uploaded source

Built Distribution

vrun-0.4-py2.py3-none-any.whl (10.5 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page