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