Per-User Customization¶
The end-user customization scripts are either sourced (allowing them to modify your shell environment) or run as an external program at the appropriate trigger time.
The global scripts applied to all environments should be placed in the
directory named by VIRTUALENVWRAPPER_HOOK_DIR, which by default will be equal
to WORKON_HOME. The local scripts should be
placed in the bin
directory of the virtualenv.
Example Usage¶
As a Django developer, you likely want DJANGO_SETTINGS_MODULE to be set, and if you work on multiple projects, you want it to be specific to the project you are currently working on. Wouldn’t it be nice if it was set based on the active virtualenv? You can achieve this with Per-User Customization as follows.
If your WORKON_HOME is set to ~/.virtualenvs:
vim ~/.virtualenvs/premkvirtualenv
Edit the file so it contains the following (for a default Django setup):
# Automatically set django settings for the virtualenv
echo "export DJANGO_SETTINGS_MODULE=$1.settings" >> "$1/bin/activate"
Create a new virtualenv, and you should see DJANGO_SETTINGS_MODULE in your env!
get_env_details¶
- Global/Local:
both
- Argument(s):
env name
- Sourced/Run:
run
$VIRTUALENVWRAPPER_HOOK_DIR/get_env_details
is run when workon
is run with no
arguments and a list of the virtual environments is printed. The hook
is run once for each environment, after the name is printed, and can
print additional information about that environment.
initialize¶
- Global/Local:
global
- Argument(s):
None
- Sourced/Run:
sourced
$VIRTUALENVWRAPPER_HOOK_DIR/initialize
is sourced when virtualenvwrapper.sh
is loaded into your environment. Use it to adjust global settings
when virtualenvwrapper is enabled.
premkvirtualenv¶
- Global/Local:
global
- Argument(s):
name of new environment
- Sourced/Run:
run
$VIRTUALENVWRAPPER_HOOK_DIR/premkvirtualenv
is run as an external program after
the virtual environment is created but before the current environment
is switched to point to the new env. The current working directory for
the script is $WORKON_HOME
and the name of the new environment is
passed as an argument to the script.
postmkvirtualenv¶
- Global/Local:
global
- Argument(s):
none
- Sourced/Run:
sourced
$VIRTUALENVWRAPPER_HOOK_DIR/postmkvirtualenv
is sourced after the new environment
is created and activated. If the -a
<project_path> flag was used,
the link to the project directory is set up before this script is sourced.
precpvirtualenv¶
- Global/Local:
global
- Argument(s):
name of original environment, name of new environment
- Sourced/Run:
run
$VIRTUALENVWRAPPER_HOOK_DIR/precpvirtualenv
is run as an external program after
the source environment is duplicated and made relocatable, but before
the premkvirtualenv
hook is run or the current environment is
switched to point to the new env. The current working directory for
the script is $WORKON_HOME
and the names of the source and new
environments are passed as arguments to the script.
postcpvirtualenv¶
- Global/Local:
global
- Argument(s):
none
- Sourced/Run:
sourced
$VIRTUALENVWRAPPER_HOOK_DIR/postcpvirtualenv
is sourced after the new environment
is created and activated.
preactivate¶
- Global/Local:
global, local
- Argument(s):
environment name
- Sourced/Run:
run
The global $VIRTUALENVWRAPPER_HOOK_DIR/preactivate
script is run before the new
environment is enabled. The environment name is passed as the first
argument.
The local $VIRTUAL_ENV/bin/preactivate
hook is run before the new
environment is enabled. The environment name is passed as the first
argument.
postactivate¶
- Global/Local:
global, local
- Argument(s):
none
- Sourced/Run:
sourced
The global $VIRTUALENVWRAPPER_HOOK_DIR/postactivate
script is sourced after the
new environment is enabled. $VIRTUAL_ENV
refers to the new
environment at the time the script runs.
This example script adds a space between the virtual environment name
and your old PS1 by making use of _OLD_VIRTUAL_PS1
.
PS1="(`basename \"$VIRTUAL_ENV\"`) $_OLD_VIRTUAL_PS1"
The local $VIRTUAL_ENV/bin/postactivate
script is sourced after
the new environment is enabled. $VIRTUAL_ENV
refers to the new
environment at the time the script runs.
This example script for the PyMOTW environment changes the current working directory and the PATH variable to refer to the source tree containing the PyMOTW source.
pymotw_root=/Users/dhellmann/Documents/PyMOTW
cd $pymotw_root
PATH=$pymotw_root/bin:$PATH
predeactivate¶
- Global/Local:
local, global
- Argument(s):
none
- Sourced/Run:
sourced
The local $VIRTUAL_ENV/bin/predeactivate
script is sourced before the
current environment is deactivated, and can be used to disable or
clear settings in your environment. $VIRTUAL_ENV
refers to the old
environment at the time the script runs.
The global $VIRTUALENVWRAPPER_HOOK_DIR/predeactivate
script is sourced before the
current environment is deactivated. $VIRTUAL_ENV
refers to the
old environment at the time the script runs.
postdeactivate¶
- Global/Local:
local, global
- Argument(s):
none
- Sourced/Run:
sourced
The $VIRTUAL_ENV/bin/postdeactivate
script is sourced after the
current environment is deactivated, and can be used to disable or
clear settings in your environment. The path to the environment just
deactivated is available in $VIRTUALENVWRAPPER_LAST_VIRTUALENV
.
prermvirtualenv¶
- Global/Local:
global
- Argument(s):
environment name
- Sourced/Run:
run
The $VIRTUALENVWRAPPER_HOOK_DIR/prermvirtualenv
script is run as an external
program before the environment is removed. The full path to the
environment directory is passed as an argument to the script.
postrmvirtualenv¶
- Global/Local:
global
- Argument(s):
environment name
- Sourced/Run:
run
The $VIRTUALENVWRAPPER_HOOK_DIR/postrmvirtualenv
script is run as an external
program after the environment is removed. The full path to the
environment directory is passed as an argument to the script.
premkproject¶
- Global/Local:
global
- Argument(s):
name of new project
- Sourced/Run:
run
$WORKON_HOME/premkproject
is run as an external program after the
virtual environment is created and after the current environment is
switched to point to the new env, but before the new project directory
is created. The current working directory for the script is
$PROJECT_HOME
and the name of the new project is passed as an
argument to the script.
postmkproject¶
- Global/Local:
global
- Argument(s):
none
- Sourced/Run:
sourced
$WORKON_HOME/postmkproject
is sourced after the new environment
and project directories are created and the virtualenv is activated.
The current working directory is the project directory.