Configuration

Shell selection

This venv-management package delegates most operations to one of the virtualenvwrapper or equivalent tools, which are implemented using shell scripts and shell functions. In order to invoke these scripts and functions successfully the shell environment mush have been correctly configured. By default venv-management attempts to use the current user’s preferred shell by examining the $SHELL environment variable. This can be overridden by setting the $VENV_MANAGEMENT_SHELL variable with a shell executable name or the path to a shell executable, for example:

export VENV_MANAGEMENT_SHELL=zsh

If neither $SHELL nor $VENV_MANAGEMENT_SHELL are set, an attempt to use bash will be made.

Shell configuration

The selected shell must be configured to make the virtualenvwrapper commands available. By default, venv-management will source the rc file corresponding to the selected shell, for example .bashrc for bash, .zshrc for zsh, and so on, on the basis that virtualenvwrapper initialization is often performed from these files. If the rc file for the selected shell can only be usefully sourced in an interactive shell, set VENV_MANAGEMENT_INTERACTIVE_SHELL to yes:

export VENV_MANAGEMENT_INTERACTIVE_SHELL=yes

Should you wish to specify a different file for shell configuration, provide its path in the VENV_MANAGEMENT_SETUP_FILEPATH environment variable. For example, since .bashrc may return immediately in non-interactive shells, and only login shells source .profile on start-up, you may want to set up virtualenvwrapper or an equivalent in in a separate file, in this example called .venvwraprc:

# .venvwraprc
source /usr/local/bin/virtualenvwrapper.sh

and then source this file in turn from, say, .bashrc.

If the VENV_MANAGEMENT_USE_SETUP variable is set to yes, the script whose filepath is specified in the VENV_MANAGEMENT_SETUP_FILEPATH variable will be as necessary before executing the commands run by this package:

export VENV_MANAGEMENT_USE_SETUP=yes
export VENV_MANAGEMENT_SETUP_FILEPATH=$HOME/.venvwraprc

You can also source this custom config file in a shell-specific rc file using the source or . command, so that virtualenvwrapper could be used in interactive shells.

Driver preference

If you have multiple virtualenv wrapper implementations installed, you can specify the order in which they will be tried with the VENV_MANAGEMENT_PREFERRED_DRIVERS environment variable. The first working implementation will be used:

export VENV_MANAGEMENT_PREFERRED_DRIVERS="virtualenvwrapper,virtualenv-sh"

Configuring for use with pyenv and pyenv-virtualenvwrapper

The pyenv tool helps with managing multiple Python versions simultaneously. The pyenv-virtualenvwrapper plugin for pyenv, helps with making virtualenvwrapper available to Python environments made using pyenv.

Make a file called .venvwraprc containing command to initialize both pyenv and pyenv-virtualenvwrapper according to your needs:

export PYENV_ROOT=$HOME/.pyenv
export PATH=$PYENV_ROOT/bin:$PATH
eval "$(pyenv init -)"
eval "$(pyenv init --path)"
pyenv virtualenvwrapper

This file can be placed in, say, your home directory. You can source this file from your preferred shell’s rc file (e.g. .bashrc) in order ensure both pyenv and virtualenvwrapper are available in your interactive shell sessions.

In the environment of the Python program which uses this venv-management package set these environment variables:

export VENV_MANAGEMENT_USE_SETUP=yes
export VENV_MANAGEMENT_SETUP_FILEPATH=$HOME/.venvwraprc

This will allow venv-management to ensure that virtualenvwrapper is properly initialized before its commands are executed.