1Reference Guide 2=============== 3 4``virtualenv`` Command 5---------------------- 6 7.. _usage: 8 9Usage 10~~~~~ 11 12:command:`virtualenv [OPTIONS] ENV_DIR` 13 14 Where ``ENV_DIR`` is an absolute or relative path to a directory to create 15 the virtual environment in. 16 17.. _options: 18 19Options 20~~~~~~~ 21 22.. program: virtualenv 23 24.. option:: --version 25 26 show program's version number and exit 27 28.. option:: -h, --help 29 30 show this help message and exit 31 32.. option:: -v, --verbose 33 34 Increase verbosity. 35 36.. option:: -q, --quiet 37 38 Decrease verbosity. 39 40.. option:: -p PYTHON_EXE, --python=PYTHON_EXE 41 42 The Python interpreter to use, e.g., 43 --python=python2.5 will use the python2.5 interpreter 44 to create the new environment. The default is the 45 interpreter that virtualenv was installed with 46 (like ``/usr/bin/python``) 47 48.. option:: --clear 49 50 Clear out the non-root install and start from scratch. 51 52.. option:: --system-site-packages 53 54 Give the virtual environment access to the global 55 site-packages. 56 57.. option:: --always-copy 58 59 Always copy files rather than symlinking. 60 61.. option:: --relocatable 62 63 Make an EXISTING virtualenv environment relocatable. 64 This fixes up scripts and makes all .pth files relative. 65 66.. option:: --unzip-setuptools 67 68 Unzip Setuptools when installing it. 69 70.. option:: --no-setuptools 71 72 Do not install setuptools in the new virtualenv. 73 74.. option:: --no-pip 75 76 Do not install pip in the new virtualenv. 77 78.. option:: --no-wheel 79 80 Do not install wheel in the new virtualenv. 81 82.. option:: --extra-search-dir=DIR 83 84 Directory to look for setuptools/pip distributions in. 85 This option can be specified multiple times. 86 87.. option:: --prompt=PROMPT 88 89 Provides an alternative prompt prefix for this 90 environment. 91 92.. option:: --download 93 94 Download preinstalled packages from PyPI. 95 96.. option:: --no-download 97 98 Do not download preinstalled packages from PyPI. 99 100.. option:: --no-site-packages 101 102 DEPRECATED. Retained only for backward compatibility. 103 Not having access to global site-packages is now the 104 default behavior. 105 106.. option:: --distribute 107.. option:: --setuptools 108 109 Legacy; now have no effect. Before version 1.10 these could be used 110 to choose whether to install Distribute_ or Setuptools_ into the created 111 virtualenv. Distribute has now been merged into Setuptools, and the 112 latter is always installed. 113 114.. _Distribute: https://pypi.python.org/pypi/distribute 115.. _Setuptools: https://pypi.python.org/pypi/setuptools 116 117 118Configuration 119------------- 120 121Environment Variables 122~~~~~~~~~~~~~~~~~~~~~ 123 124Each command line option is automatically used to look for environment 125variables with the name format ``VIRTUALENV_<UPPER_NAME>``. That means 126the name of the command line options are capitalized and have dashes 127(``'-'``) replaced with underscores (``'_'``). 128 129For example, to automatically use a custom Python binary instead of the 130one virtualenv is run with you can also set an environment variable:: 131 132 $ export VIRTUALENV_PYTHON=/opt/python-3.3/bin/python 133 $ virtualenv ENV 134 135It's the same as passing the option to virtualenv directly:: 136 137 $ virtualenv --python=/opt/python-3.3/bin/python ENV 138 139This also works for appending command line options, like ``--find-links``. 140Just leave an empty space between the passed values, e.g.:: 141 142 $ export VIRTUALENV_EXTRA_SEARCH_DIR="/path/to/dists /path/to/other/dists" 143 $ virtualenv ENV 144 145is the same as calling:: 146 147 $ virtualenv --extra-search-dir=/path/to/dists --extra-search-dir=/path/to/other/dists ENV 148 149.. envvar:: VIRTUAL_ENV_DISABLE_PROMPT 150 151 Any virtualenv created when this is set to a non-empty value will not have 152 it's :ref:`activate` modify the shell prompt. 153 154 155Configuration File 156~~~~~~~~~~~~~~~~~~ 157 158virtualenv also looks for a standard ini config file. On Unix and Mac OS X 159that's ``$HOME/.virtualenv/virtualenv.ini`` and on Windows, it's 160``%APPDATA%\virtualenv\virtualenv.ini``. 161 162The names of the settings are derived from the long command line option, 163e.g. the option :option:`--python <-p>` would look like this:: 164 165 [virtualenv] 166 python = /opt/python-3.3/bin/python 167 168Appending options like :option:`--extra-search-dir` can be written on multiple 169lines:: 170 171 [virtualenv] 172 extra-search-dir = 173 /path/to/dists 174 /path/to/other/dists 175 176Please have a look at the output of :option:`--help <-h>` for a full list 177of supported options. 178 179 180Extending Virtualenv 181-------------------- 182 183 184Creating Your Own Bootstrap Scripts 185~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 186 187While this creates an environment, it doesn't put anything into the 188environment. Developers may find it useful to distribute a script 189that sets up a particular environment, for example a script that 190installs a particular web application. 191 192To create a script like this, call 193:py:func:`virtualenv.create_bootstrap_script`, and write the 194result to your new bootstrapping script. 195 196.. py:function:: create_bootstrap_script(extra_text) 197 198 Creates a bootstrap script from ``extra_text``, which is like 199 this script but with extend_parser, adjust_options, and after_install hooks. 200 201This returns a string that (written to disk of course) can be used 202as a bootstrap script with your own customizations. The script 203will be the standard virtualenv.py script, with your extra text 204added (your extra text should be Python code). 205 206If you include these functions, they will be called: 207 208.. py:function:: extend_parser(optparse_parser) 209 210 You can add or remove options from the parser here. 211 212.. py:function:: adjust_options(options, args) 213 214 You can change options here, or change the args (if you accept 215 different kinds of arguments, be sure you modify ``args`` so it is 216 only ``[DEST_DIR]``). 217 218.. py:function:: after_install(options, home_dir) 219 220 After everything is installed, this function is called. This 221 is probably the function you are most likely to use. An 222 example would be:: 223 224 def after_install(options, home_dir): 225 if sys.platform == 'win32': 226 bin = 'Scripts' 227 else: 228 bin = 'bin' 229 subprocess.call([join(home_dir, bin, 'easy_install'), 230 'MyPackage']) 231 subprocess.call([join(home_dir, bin, 'my-package-script'), 232 'setup', home_dir]) 233 234 This example immediately installs a package, and runs a setup 235 script from that package. 236 237Bootstrap Example 238~~~~~~~~~~~~~~~~~ 239 240Here's a more concrete example of how you could use this:: 241 242 import virtualenv, textwrap 243 output = virtualenv.create_bootstrap_script(textwrap.dedent(""" 244 import os, subprocess 245 def after_install(options, home_dir): 246 etc = join(home_dir, 'etc') 247 if not os.path.exists(etc): 248 os.makedirs(etc) 249 subprocess.call([join(home_dir, 'bin', 'easy_install'), 250 'BlogApplication']) 251 subprocess.call([join(home_dir, 'bin', 'paster'), 252 'make-config', 'BlogApplication', 253 join(etc, 'blog.ini')]) 254 subprocess.call([join(home_dir, 'bin', 'paster'), 255 'setup-app', join(etc, 'blog.ini')]) 256 """)) 257 f = open('blog-bootstrap.py', 'w').write(output) 258 259Another example is available `here`__. 260 261.. __: https://github.com/socialplanning/fassembler/blob/master/fassembler/create-venv-script.py 262