1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/python/virtualenv/docs/virtualenv.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,595 @@
1.4 +
1.5 +Introduction
1.6 +------------
1.7 +
1.8 +``virtualenv`` is a tool to create isolated Python environments.
1.9 +
1.10 +The basic problem being addressed is one of dependencies and versions,
1.11 +and indirectly permissions. Imagine you have an application that
1.12 +needs version 1 of LibFoo, but another application requires version
1.13 +2. How can you use both these applications? If you install
1.14 +everything into ``/usr/lib/python2.7/site-packages`` (or whatever your
1.15 +platform's standard location is), it's easy to end up in a situation
1.16 +where you unintentionally upgrade an application that shouldn't be
1.17 +upgraded.
1.18 +
1.19 +Or more generally, what if you want to install an application *and
1.20 +leave it be*? If an application works, any change in its libraries or
1.21 +the versions of those libraries can break the application.
1.22 +
1.23 +Also, what if you can't install packages into the global
1.24 +``site-packages`` directory? For instance, on a shared host.
1.25 +
1.26 +In all these cases, ``virtualenv`` can help you. It creates an
1.27 +environment that has its own installation directories, that doesn't
1.28 +share libraries with other virtualenv environments (and optionally
1.29 +doesn't access the globally installed libraries either).
1.30 +
1.31 +
1.32 +Installation
1.33 +------------
1.34 +
1.35 +.. warning::
1.36 +
1.37 + We advise installing virtualenv-1.9 or greater. Prior to version 1.9, the
1.38 + pip included in virtualenv did not not download from PyPI over SSL.
1.39 +
1.40 +.. warning::
1.41 +
1.42 + When using pip to install virtualenv, we advise using pip 1.3 or greater.
1.43 + Prior to version 1.3, pip did not not download from PyPI over SSL.
1.44 +
1.45 +.. warning::
1.46 +
1.47 + We advise against using easy_install to install virtualenv when using
1.48 + setuptools < 0.9.7, because easy_install didn't download from PyPI over SSL
1.49 + and was broken in some subtle ways.
1.50 +
1.51 +To install globally with `pip` (if you have pip 1.3 or greater installed globally):
1.52 +
1.53 +::
1.54 +
1.55 + $ [sudo] pip install virtualenv
1.56 +
1.57 +Or to get the latest unreleased dev version:
1.58 +
1.59 +::
1.60 +
1.61 + $ [sudo] pip install https://github.com/pypa/virtualenv/tarball/develop
1.62 +
1.63 +
1.64 +To install globally from source:
1.65 +
1.66 +::
1.67 +
1.68 + $ curl -O https://pypi.python.org/packages/source/v/virtualenv/virtualenv-X.X.tar.gz
1.69 + $ tar xvfz virtualenv-X.X.tar.gz
1.70 + $ cd virtualenv-X.X
1.71 + $ [sudo] python setup.py install
1.72 +
1.73 +
1.74 +To *use* locally from source:
1.75 +
1.76 +::
1.77 +
1.78 + $ curl -O https://pypi.python.org/packages/source/v/virtualenv/virtualenv-X.X.tar.gz
1.79 + $ tar xvfz virtualenv-X.X.tar.gz
1.80 + $ cd virtualenv-X.X
1.81 + $ python virtualenv.py myVE
1.82 +
1.83 +.. note::
1.84 +
1.85 + The ``virtualenv.py`` script is *not* supported if run without the
1.86 + necessary pip/setuptools/virtualenv distributions available locally. All
1.87 + of the installation methods above include a ``virtualenv_support``
1.88 + directory alongside ``virtualenv.py`` which contains a complete set of
1.89 + pip and setuptools distributions, and so are fully supported.
1.90 +
1.91 +Usage
1.92 +-----
1.93 +
1.94 +The basic usage is::
1.95 +
1.96 + $ virtualenv ENV
1.97 +
1.98 +This creates ``ENV/lib/pythonX.X/site-packages``, where any libraries you
1.99 +install will go. It also creates ``ENV/bin/python``, which is a Python
1.100 +interpreter that uses this environment. Anytime you use that interpreter
1.101 +(including when a script has ``#!/path/to/ENV/bin/python`` in it) the libraries
1.102 +in that environment will be used.
1.103 +
1.104 +It also installs `Setuptools
1.105 +<http://peak.telecommunity.com/DevCenter/setuptools>`_ into the environment.
1.106 +
1.107 +.. note::
1.108 +
1.109 + Virtualenv (<1.10) used to provide a ``--distribute`` option to use the
1.110 + setuptools fork Distribute_. Since Distribute has been merged back into
1.111 + setuptools this option is now no-op, it will always use the improved
1.112 + setuptools releases.
1.113 +
1.114 +A new virtualenv also includes the `pip <http://pypi.python.org/pypi/pip>`_
1.115 +installer, so you can use ``ENV/bin/pip`` to install additional packages into
1.116 +the environment.
1.117 +
1.118 +.. _Distribute: https://pypi.python.org/pypi/distribute
1.119 +
1.120 +activate script
1.121 +~~~~~~~~~~~~~~~
1.122 +
1.123 +In a newly created virtualenv there will be a ``bin/activate`` shell
1.124 +script. For Windows systems, activation scripts are provided for CMD.exe
1.125 +and Powershell.
1.126 +
1.127 +On Posix systems you can do::
1.128 +
1.129 + $ source bin/activate
1.130 +
1.131 +This will change your ``$PATH`` so its first entry is the virtualenv's
1.132 +``bin/`` directory. (You have to use ``source`` because it changes your
1.133 +shell environment in-place.) This is all it does; it's purely a
1.134 +convenience. If you directly run a script or the python interpreter
1.135 +from the virtualenv's ``bin/`` directory (e.g. ``path/to/env/bin/pip``
1.136 +or ``/path/to/env/bin/python script.py``) there's no need for
1.137 +activation.
1.138 +
1.139 +After activating an environment you can use the function ``deactivate`` to
1.140 +undo the changes to your ``$PATH``.
1.141 +
1.142 +The ``activate`` script will also modify your shell prompt to indicate
1.143 +which environment is currently active. You can disable this behavior,
1.144 +which can be useful if you have your own custom prompt that already
1.145 +displays the active environment name. To do so, set the
1.146 +``VIRTUAL_ENV_DISABLE_PROMPT`` environment variable to any non-empty
1.147 +value before running the ``activate`` script.
1.148 +
1.149 +On Windows you just do::
1.150 +
1.151 + > \path\to\env\Scripts\activate
1.152 +
1.153 +And type `deactivate` to undo the changes.
1.154 +
1.155 +Based on your active shell (CMD.exe or Powershell.exe), Windows will use
1.156 +either activate.bat or activate.ps1 (as appropriate) to activate the
1.157 +virtual environment. If using Powershell, see the notes about code signing
1.158 +below.
1.159 +
1.160 +.. note::
1.161 +
1.162 + If using Powershell, the ``activate`` script is subject to the
1.163 + `execution policies`_ on the system. By default on Windows 7, the system's
1.164 + excution policy is set to ``Restricted``, meaning no scripts like the
1.165 + ``activate`` script are allowed to be executed. But that can't stop us
1.166 + from changing that slightly to allow it to be executed.
1.167 +
1.168 + In order to use the script, you have to relax your system's execution
1.169 + policy to ``AllSigned``, meaning all scripts on the system must be
1.170 + digitally signed to be executed. Since the virtualenv activation
1.171 + script is signed by one of the authors (Jannis Leidel) this level of
1.172 + the execution policy suffices. As an administrator run::
1.173 +
1.174 + PS C:\> Set-ExecutionPolicy AllSigned
1.175 +
1.176 + Then you'll be asked to trust the signer, when executing the script.
1.177 + You will be prompted with the following::
1.178 +
1.179 + PS C:\> virtualenv .\foo
1.180 + New python executable in C:\foo\Scripts\python.exe
1.181 + Installing setuptools................done.
1.182 + Installing pip...................done.
1.183 + PS C:\> .\foo\scripts\activate
1.184 +
1.185 + Do you want to run software from this untrusted publisher?
1.186 + File C:\foo\scripts\activate.ps1 is published by E=jannis@leidel.info,
1.187 + CN=Jannis Leidel, L=Berlin, S=Berlin, C=DE, Description=581796-Gh7xfJxkxQSIO4E0
1.188 + and is not trusted on your system. Only run scripts from trusted publishers.
1.189 + [V] Never run [D] Do not run [R] Run once [A] Always run [?] Help
1.190 + (default is "D"):A
1.191 + (foo) PS C:\>
1.192 +
1.193 + If you select ``[A] Always Run``, the certificate will be added to the
1.194 + Trusted Publishers of your user account, and will be trusted in this
1.195 + user's context henceforth. If you select ``[R] Run Once``, the script will
1.196 + be run, but you will be prometed on a subsequent invocation. Advanced users
1.197 + can add the signer's certificate to the Trusted Publishers of the Computer
1.198 + account to apply to all users (though this technique is out of scope of this
1.199 + document).
1.200 +
1.201 + Alternatively, you may relax the system execution policy to allow running
1.202 + of local scripts without verifying the code signature using the following::
1.203 +
1.204 + PS C:\> Set-ExecutionPolicy RemoteSigned
1.205 +
1.206 + Since the ``activate.ps1`` script is generated locally for each virtualenv,
1.207 + it is not considered a remote script and can then be executed.
1.208 +
1.209 +.. _`execution policies`: http://technet.microsoft.com/en-us/library/dd347641.aspx
1.210 +
1.211 +The ``--system-site-packages`` Option
1.212 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.213 +
1.214 +If you build with ``virtualenv --system-site-packages ENV``, your virtual
1.215 +environment will inherit packages from ``/usr/lib/python2.7/site-packages``
1.216 +(or wherever your global site-packages directory is).
1.217 +
1.218 +This can be used if you have control over the global site-packages directory,
1.219 +and you want to depend on the packages there. If you want isolation from the
1.220 +global system, do not use this flag.
1.221 +
1.222 +
1.223 +Environment variables and configuration files
1.224 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.225 +
1.226 +virtualenv can not only be configured by passing command line options such as
1.227 +``--python`` but also by two other means:
1.228 +
1.229 +- Environment variables
1.230 +
1.231 + Each command line option is automatically used to look for environment
1.232 + variables with the name format ``VIRTUALENV_<UPPER_NAME>``. That means
1.233 + the name of the command line options are capitalized and have dashes
1.234 + (``'-'``) replaced with underscores (``'_'``).
1.235 +
1.236 + For example, to automatically use a custom Python binary instead of the
1.237 + one virtualenv is run with you can also set an environment variable::
1.238 +
1.239 + $ export VIRTUALENV_PYTHON=/opt/python-3.3/bin/python
1.240 + $ virtualenv ENV
1.241 +
1.242 + It's the same as passing the option to virtualenv directly::
1.243 +
1.244 + $ virtualenv --python=/opt/python-3.3/bin/python ENV
1.245 +
1.246 + This also works for appending command line options, like ``--find-links``.
1.247 + Just leave an empty space between the passsed values, e.g.::
1.248 +
1.249 + $ export VIRTUALENV_EXTRA_SEARCH_DIR="/path/to/dists /path/to/other/dists"
1.250 + $ virtualenv ENV
1.251 +
1.252 + is the same as calling::
1.253 +
1.254 + $ virtualenv --extra-search-dir=/path/to/dists --extra-search-dir=/path/to/other/dists ENV
1.255 +
1.256 +- Config files
1.257 +
1.258 + virtualenv also looks for a standard ini config file. On Unix and Mac OS X
1.259 + that's ``$HOME/.virtualenv/virtualenv.ini`` and on Windows, it's
1.260 + ``%APPDATA%\virtualenv\virtualenv.ini``.
1.261 +
1.262 + The names of the settings are derived from the long command line option,
1.263 + e.g. the option ``--python`` would look like this::
1.264 +
1.265 + [virtualenv]
1.266 + python = /opt/python-3.3/bin/python
1.267 +
1.268 + Appending options like ``--extra-search-dir`` can be written on multiple
1.269 + lines::
1.270 +
1.271 + [virtualenv]
1.272 + extra-search-dir =
1.273 + /path/to/dists
1.274 + /path/to/other/dists
1.275 +
1.276 +Please have a look at the output of ``virtualenv --help`` for a full list
1.277 +of supported options.
1.278 +
1.279 +Windows Notes
1.280 +~~~~~~~~~~~~~
1.281 +
1.282 +Some paths within the virtualenv are slightly different on Windows: scripts and
1.283 +executables on Windows go in ``ENV\Scripts\`` instead of ``ENV/bin/`` and
1.284 +libraries go in ``ENV\Lib\`` rather than ``ENV/lib/``.
1.285 +
1.286 +To create a virtualenv under a path with spaces in it on Windows, you'll need
1.287 +the `win32api <http://sourceforge.net/projects/pywin32/>`_ library installed.
1.288 +
1.289 +PyPy Support
1.290 +~~~~~~~~~~~~
1.291 +
1.292 +Beginning with virtualenv version 1.5 `PyPy <http://pypy.org>`_ is
1.293 +supported. To use PyPy 1.4 or 1.4.1, you need a version of virtualenv >= 1.5.
1.294 +To use PyPy 1.5, you need a version of virtualenv >= 1.6.1.
1.295 +
1.296 +Creating Your Own Bootstrap Scripts
1.297 +-----------------------------------
1.298 +
1.299 +While this creates an environment, it doesn't put anything into the
1.300 +environment. Developers may find it useful to distribute a script
1.301 +that sets up a particular environment, for example a script that
1.302 +installs a particular web application.
1.303 +
1.304 +To create a script like this, call
1.305 +``virtualenv.create_bootstrap_script(extra_text)``, and write the
1.306 +result to your new bootstrapping script. Here's the documentation
1.307 +from the docstring:
1.308 +
1.309 +Creates a bootstrap script, which is like this script but with
1.310 +extend_parser, adjust_options, and after_install hooks.
1.311 +
1.312 +This returns a string that (written to disk of course) can be used
1.313 +as a bootstrap script with your own customizations. The script
1.314 +will be the standard virtualenv.py script, with your extra text
1.315 +added (your extra text should be Python code).
1.316 +
1.317 +If you include these functions, they will be called:
1.318 +
1.319 +``extend_parser(optparse_parser)``:
1.320 + You can add or remove options from the parser here.
1.321 +
1.322 +``adjust_options(options, args)``:
1.323 + You can change options here, or change the args (if you accept
1.324 + different kinds of arguments, be sure you modify ``args`` so it is
1.325 + only ``[DEST_DIR]``).
1.326 +
1.327 +``after_install(options, home_dir)``:
1.328 +
1.329 + After everything is installed, this function is called. This
1.330 + is probably the function you are most likely to use. An
1.331 + example would be::
1.332 +
1.333 + def after_install(options, home_dir):
1.334 + if sys.platform == 'win32':
1.335 + bin = 'Scripts'
1.336 + else:
1.337 + bin = 'bin'
1.338 + subprocess.call([join(home_dir, bin, 'easy_install'),
1.339 + 'MyPackage'])
1.340 + subprocess.call([join(home_dir, bin, 'my-package-script'),
1.341 + 'setup', home_dir])
1.342 +
1.343 + This example immediately installs a package, and runs a setup
1.344 + script from that package.
1.345 +
1.346 +Bootstrap Example
1.347 +~~~~~~~~~~~~~~~~~
1.348 +
1.349 +Here's a more concrete example of how you could use this::
1.350 +
1.351 + import virtualenv, textwrap
1.352 + output = virtualenv.create_bootstrap_script(textwrap.dedent("""
1.353 + import os, subprocess
1.354 + def after_install(options, home_dir):
1.355 + etc = join(home_dir, 'etc')
1.356 + if not os.path.exists(etc):
1.357 + os.makedirs(etc)
1.358 + subprocess.call([join(home_dir, 'bin', 'easy_install'),
1.359 + 'BlogApplication'])
1.360 + subprocess.call([join(home_dir, 'bin', 'paster'),
1.361 + 'make-config', 'BlogApplication',
1.362 + join(etc, 'blog.ini')])
1.363 + subprocess.call([join(home_dir, 'bin', 'paster'),
1.364 + 'setup-app', join(etc, 'blog.ini')])
1.365 + """))
1.366 + f = open('blog-bootstrap.py', 'w').write(output)
1.367 +
1.368 +Another example is available `here
1.369 +<https://github.com/socialplanning/fassembler/blob/master/fassembler/create-venv-script.py>`_.
1.370 +
1.371 +
1.372 +Using Virtualenv without ``bin/python``
1.373 +---------------------------------------
1.374 +
1.375 +Sometimes you can't or don't want to use the Python interpreter
1.376 +created by the virtualenv. For instance, in a `mod_python
1.377 +<http://www.modpython.org/>`_ or `mod_wsgi <http://www.modwsgi.org/>`_
1.378 +environment, there is only one interpreter.
1.379 +
1.380 +Luckily, it's easy. You must use the custom Python interpreter to
1.381 +*install* libraries. But to *use* libraries, you just have to be sure
1.382 +the path is correct. A script is available to correct the path. You
1.383 +can setup the environment like::
1.384 +
1.385 + activate_this = '/path/to/env/bin/activate_this.py'
1.386 + execfile(activate_this, dict(__file__=activate_this))
1.387 +
1.388 +This will change ``sys.path`` and even change ``sys.prefix``, but also allow
1.389 +you to use an existing interpreter. Items in your environment will show up
1.390 +first on ``sys.path``, before global items. However, global items will
1.391 +always be accessible (as if the ``--system-site-packages`` flag had been used
1.392 +in creating the environment, whether it was or not). Also, this cannot undo
1.393 +the activation of other environments, or modules that have been imported.
1.394 +You shouldn't try to, for instance, activate an environment before a web
1.395 +request; you should activate *one* environment as early as possible, and not
1.396 +do it again in that process.
1.397 +
1.398 +Making Environments Relocatable
1.399 +-------------------------------
1.400 +
1.401 +Note: this option is somewhat experimental, and there are probably
1.402 +caveats that have not yet been identified.
1.403 +
1.404 +.. warning::
1.405 +
1.406 + The ``--relocatable`` option currently has a number of issues,
1.407 + and is not guaranteed to work in all circumstances. It is possible
1.408 + that the option will be deprecated in a future version of ``virtualenv``.
1.409 +
1.410 +Normally environments are tied to a specific path. That means that
1.411 +you cannot move an environment around or copy it to another computer.
1.412 +You can fix up an environment to make it relocatable with the
1.413 +command::
1.414 +
1.415 + $ virtualenv --relocatable ENV
1.416 +
1.417 +This will make some of the files created by setuptools use relative paths,
1.418 +and will change all the scripts to use ``activate_this.py`` instead of using
1.419 +the location of the Python interpreter to select the environment.
1.420 +
1.421 +**Note:** scripts which have been made relocatable will only work if
1.422 +the virtualenv is activated, specifically the python executable from
1.423 +the virtualenv must be the first one on the system PATH. Also note that
1.424 +the activate scripts are not currently made relocatable by
1.425 +``virtualenv --relocatable``.
1.426 +
1.427 +**Note:** you must run this after you've installed *any* packages into
1.428 +the environment. If you make an environment relocatable, then
1.429 +install a new package, you must run ``virtualenv --relocatable``
1.430 +again.
1.431 +
1.432 +Also, this **does not make your packages cross-platform**. You can
1.433 +move the directory around, but it can only be used on other similar
1.434 +computers. Some known environmental differences that can cause
1.435 +incompatibilities: a different version of Python, when one platform
1.436 +uses UCS2 for its internal unicode representation and another uses
1.437 +UCS4 (a compile-time option), obvious platform changes like Windows
1.438 +vs. Linux, or Intel vs. ARM, and if you have libraries that bind to C
1.439 +libraries on the system, if those C libraries are located somewhere
1.440 +different (either different versions, or a different filesystem
1.441 +layout).
1.442 +
1.443 +If you use this flag to create an environment, currently, the
1.444 +``--system-site-packages`` option will be implied.
1.445 +
1.446 +The ``--extra-search-dir`` option
1.447 +---------------------------------
1.448 +
1.449 +This option allows you to provide your own versions of setuptools and/or
1.450 +pip to use instead of the embedded versions that come with virtualenv.
1.451 +
1.452 +To use this feature, pass one or more ``--extra-search-dir`` options to
1.453 +virtualenv like this::
1.454 +
1.455 + $ virtualenv --extra-search-dir=/path/to/distributions ENV
1.456 +
1.457 +The ``/path/to/distributions`` path should point to a directory that contains
1.458 +setuptools and/or pip wheels.
1.459 +
1.460 +virtualenv will look for wheels in the specified directories, but will use
1.461 +pip's standard algorithm for selecting the wheel to install, which looks for
1.462 +the latest compatible wheel.
1.463 +
1.464 +As well as the extra directories, the search order includes:
1.465 +
1.466 +#. The ``virtualenv_support`` directory relative to virtualenv.py
1.467 +#. The directory where virtualenv.py is located.
1.468 +#. The current directory.
1.469 +
1.470 +If no satisfactory local distributions are found, virtualenv will
1.471 +fail. Virtualenv will never download packages.
1.472 +
1.473 +
1.474 +Compare & Contrast with Alternatives
1.475 +------------------------------------
1.476 +
1.477 +There are several alternatives that create isolated environments:
1.478 +
1.479 +* ``workingenv`` (which I do not suggest you use anymore) is the
1.480 + predecessor to this library. It used the main Python interpreter,
1.481 + but relied on setting ``$PYTHONPATH`` to activate the environment.
1.482 + This causes problems when running Python scripts that aren't part of
1.483 + the environment (e.g., a globally installed ``hg`` or ``bzr``). It
1.484 + also conflicted a lot with Setuptools.
1.485 +
1.486 +* `virtual-python
1.487 + <http://peak.telecommunity.com/DevCenter/EasyInstall#creating-a-virtual-python>`_
1.488 + is also a predecessor to this library. It uses only symlinks, so it
1.489 + couldn't work on Windows. It also symlinks over the *entire*
1.490 + standard library and global ``site-packages``. As a result, it
1.491 + won't see new additions to the global ``site-packages``.
1.492 +
1.493 + This script only symlinks a small portion of the standard library
1.494 + into the environment, and so on Windows it is feasible to simply
1.495 + copy these files over. Also, it creates a new/empty
1.496 + ``site-packages`` and also adds the global ``site-packages`` to the
1.497 + path, so updates are tracked separately. This script also installs
1.498 + Setuptools automatically, saving a step and avoiding the need for
1.499 + network access.
1.500 +
1.501 +* `zc.buildout <http://pypi.python.org/pypi/zc.buildout>`_ doesn't
1.502 + create an isolated Python environment in the same style, but
1.503 + achieves similar results through a declarative config file that sets
1.504 + up scripts with very particular packages. As a declarative system,
1.505 + it is somewhat easier to repeat and manage, but more difficult to
1.506 + experiment with. ``zc.buildout`` includes the ability to setup
1.507 + non-Python systems (e.g., a database server or an Apache instance).
1.508 +
1.509 +I *strongly* recommend anyone doing application development or
1.510 +deployment use one of these tools.
1.511 +
1.512 +Contributing
1.513 +------------
1.514 +
1.515 +Refer to the `pip development`_ documentation - it applies equally to
1.516 +virtualenv, except that virtualenv issues should filed on the `virtualenv
1.517 +repo`_ at GitHub.
1.518 +
1.519 +Virtualenv's release schedule is tied to pip's -- each time there's a new pip
1.520 +release, there will be a new virtualenv release that bundles the new version of
1.521 +pip.
1.522 +
1.523 +Files in the `virtualenv_embedded/` subdirectory are embedded into
1.524 +`virtualenv.py` itself as base64-encoded strings (in order to support
1.525 +single-file use of `virtualenv.py` without installing it). If your patch
1.526 +changes any file in `virtualenv_embedded/`, run `bin/rebuild-script.py` to
1.527 +update the embedded version of that file in `virtualenv.py`; commit that and
1.528 +submit it as part of your patch / pull request.
1.529 +
1.530 +.. _pip development: http://www.pip-installer.org/en/latest/development.html
1.531 +.. _virtualenv repo: https://github.com/pypa/virtualenv/
1.532 +
1.533 +Running the tests
1.534 +~~~~~~~~~~~~~~~~~
1.535 +
1.536 +Virtualenv's test suite is small and not yet at all comprehensive, but we aim
1.537 +to grow it.
1.538 +
1.539 +The easy way to run tests (handles test dependencies automatically)::
1.540 +
1.541 + $ python setup.py test
1.542 +
1.543 +If you want to run only a selection of the tests, you'll need to run them
1.544 +directly with nose instead. Create a virtualenv, and install required
1.545 +packages::
1.546 +
1.547 + $ pip install nose mock
1.548 +
1.549 +Run nosetests::
1.550 +
1.551 + $ nosetests
1.552 +
1.553 +Or select just a single test file to run::
1.554 +
1.555 + $ nosetests tests.test_virtualenv
1.556 +
1.557 +
1.558 +Other Documentation and Links
1.559 +-----------------------------
1.560 +
1.561 +* James Gardner has written a tutorial on using `virtualenv with
1.562 + Pylons
1.563 + <http://wiki.pylonshq.com/display/pylonscookbook/Using+a+Virtualenv+Sandbox>`_.
1.564 +
1.565 +* `Blog announcement
1.566 + <http://blog.ianbicking.org/2007/10/10/workingenv-is-dead-long-live-virtualenv/>`_.
1.567 +
1.568 +* Doug Hellmann wrote a description of his `command-line work flow
1.569 + using virtualenv (virtualenvwrapper)
1.570 + <http://www.doughellmann.com/articles/CompletelyDifferent-2008-05-virtualenvwrapper/index.html>`_
1.571 + including some handy scripts to make working with multiple
1.572 + environments easier. He also wrote `an example of using virtualenv
1.573 + to try IPython
1.574 + <http://www.doughellmann.com/articles/CompletelyDifferent-2008-02-ipython-and-virtualenv/index.html>`_.
1.575 +
1.576 +* Chris Perkins created a `showmedo video including virtualenv
1.577 + <http://showmedo.com/videos/video?name=2910000&fromSeriesID=291>`_.
1.578 +
1.579 +* `Using virtualenv with mod_wsgi
1.580 + <http://code.google.com/p/modwsgi/wiki/VirtualEnvironments>`_.
1.581 +
1.582 +* `virtualenv commands
1.583 + <https://github.com/thisismedium/virtualenv-commands>`_ for some more
1.584 + workflow-related tools around virtualenv.
1.585 +
1.586 +Status and License
1.587 +------------------
1.588 +
1.589 +``virtualenv`` is a successor to `workingenv
1.590 +<http://cheeseshop.python.org/pypi/workingenv.py>`_, and an extension
1.591 +of `virtual-python
1.592 +<http://peak.telecommunity.com/DevCenter/EasyInstall#creating-a-virtual-python>`_.
1.593 +
1.594 +It was written by Ian Bicking, sponsored by the `Open Planning
1.595 +Project <http://openplans.org>`_ and is now maintained by a
1.596 +`group of developers <https://github.com/pypa/virtualenv/raw/master/AUTHORS.txt>`_.
1.597 +It is licensed under an
1.598 +`MIT-style permissive license <https://github.com/pypa/virtualenv/raw/master/LICENSE.txt>`_.
