| virtualenv |
| ========== |
| |
| * `Discussion list <http://groups.google.com/group/python-virtualenv/>`_ |
| * `Bugs <https://github.com/pypa/virtualenv/issues/>`_ |
| |
| .. contents:: |
| |
| .. toctree:: |
| :maxdepth: 1 |
| |
| news |
| |
| .. comment: split here |
| |
| Installation |
| ------------ |
| |
| You can install virtualenv with ``pip install virtualenv``, or the `latest |
| development version <https://github.com/pypa/virtualenv/tarball/develop>`_ |
| with ``pip install https://github.com/pypa/virtualenv/tarball/develop``. |
| |
| You can also use ``easy_install``, or if you have no Python package manager |
| available at all, you can just grab the single file `virtualenv.py`_ and run |
| it with ``python virtualenv.py``. |
| |
| .. _virtualenv.py: https://raw.github.com/pypa/virtualenv/master/virtualenv.py |
| |
| What It Does |
| ------------ |
| |
| ``virtualenv`` is a tool to create isolated Python environments. |
| |
| The basic problem being addressed is one of dependencies and versions, |
| and indirectly permissions. Imagine you have an application that |
| needs version 1 of LibFoo, but another application requires version |
| 2. How can you use both these applications? If you install |
| everything into ``/usr/lib/python2.7/site-packages`` (or whatever your |
| platform's standard location is), it's easy to end up in a situation |
| where you unintentionally upgrade an application that shouldn't be |
| upgraded. |
| |
| Or more generally, what if you want to install an application *and |
| leave it be*? If an application works, any change in its libraries or |
| the versions of those libraries can break the application. |
| |
| Also, what if you can't install packages into the global |
| ``site-packages`` directory? For instance, on a shared host. |
| |
| In all these cases, ``virtualenv`` can help you. It creates an |
| environment that has its own installation directories, that doesn't |
| share libraries with other virtualenv environments (and optionally |
| doesn't access the globally installed libraries either). |
| |
| Usage |
| ----- |
| |
| The basic usage is:: |
| |
| $ python virtualenv.py ENV |
| |
| If you install it you can also just do ``virtualenv ENV``. |
| |
| This creates ``ENV/lib/pythonX.X/site-packages``, where any libraries you |
| install will go. It also creates ``ENV/bin/python``, which is a Python |
| interpreter that uses this environment. Anytime you use that interpreter |
| (including when a script has ``#!/path/to/ENV/bin/python`` in it) the libraries |
| in that environment will be used. |
| |
| It also installs either `Setuptools |
| <http://peak.telecommunity.com/DevCenter/setuptools>`_ or `distribute |
| <http://pypi.python.org/pypi/distribute>`_ into the environment. To use |
| Distribute instead of setuptools, just call virtualenv like this:: |
| |
| $ python virtualenv.py --distribute ENV |
| |
| You can also set the environment variable VIRTUALENV_DISTRIBUTE. |
| |
| A new virtualenv also includes the `pip <http://pypi.python.org/pypi/pip>`_ |
| installer, so you can use ``ENV/bin/pip`` to install additional packages into |
| the environment. |
| |
| |
| activate script |
| ~~~~~~~~~~~~~~~ |
| |
| In a newly created virtualenv there will be a ``bin/activate`` shell |
| script. For Windows systems, activation scripts are provided for CMD.exe |
| and Powershell. |
| |
| On Posix systems you can do:: |
| |
| $ source bin/activate |
| |
| This will change your ``$PATH`` so its first entry is the virtualenv's |
| ``bin/`` directory. (You have to use ``source`` because it changes your |
| shell environment in-place.) This is all it does; it's purely a |
| convenience. If you directly run a script or the python interpreter |
| from the virtualenv's ``bin/`` directory (e.g. ``path/to/env/bin/pip`` |
| or ``/path/to/env/bin/python script.py``) there's no need for |
| activation. |
| |
| After activating an environment you can use the function ``deactivate`` to |
| undo the changes to your ``$PATH``. |
| |
| The ``activate`` script will also modify your shell prompt to indicate |
| which environment is currently active. You can disable this behavior, |
| which can be useful if you have your own custom prompt that already |
| displays the active environment name. To do so, set the |
| ``VIRTUAL_ENV_DISABLE_PROMPT`` environment variable to any non-empty |
| value before running the ``activate`` script. |
| |
| On Windows you just do:: |
| |
| > \path\to\env\Scripts\activate |
| |
| And type `deactivate` to undo the changes. |
| |
| Based on your active shell (CMD.exe or Powershell.exe), Windows will use |
| either activate.bat or activate.ps1 (as appropriate) to activate the |
| virtual environment. If using Powershell, see the notes about code signing |
| below. |
| |
| .. note:: |
| |
| If using Powershell, the ``activate`` script is subject to the |
| `execution policies`_ on the system. By default on Windows 7, the system's |
| excution policy is set to ``Restricted``, meaning no scripts like the |
| ``activate`` script are allowed to be executed. But that can't stop us |
| from changing that slightly to allow it to be executed. |
| |
| In order to use the script, you have to relax your system's execution |
| policy to ``AllSigned``, meaning all scripts on the system must be |
| digitally signed to be executed. Since the virtualenv activation |
| script is signed by one of the authors (Jannis Leidel) this level of |
| the execution policy suffices. As an administrator run:: |
| |
| PS C:\> Set-ExecutionPolicy AllSigned |
| |
| Then you'll be asked to trust the signer, when executing the script. |
| You will be prompted with the following:: |
| |
| PS C:\> virtualenv .\foo |
| New python executable in C:\foo\Scripts\python.exe |
| Installing setuptools................done. |
| Installing pip...................done. |
| PS C:\> .\foo\scripts\activate |
| |
| Do you want to run software from this untrusted publisher? |
| File C:\foo\scripts\activate.ps1 is published by E=jannis@leidel.info, |
| CN=Jannis Leidel, L=Berlin, S=Berlin, C=DE, Description=581796-Gh7xfJxkxQSIO4E0 |
| and is not trusted on your system. Only run scripts from trusted publishers. |
| [V] Never run [D] Do not run [R] Run once [A] Always run [?] Help |
| (default is "D"):A |
| (foo) PS C:\> |
| |
| If you select ``[A] Always Run``, the certificate will be added to the |
| Trusted Publishers of your user account, and will be trusted in this |
| user's context henceforth. If you select ``[R] Run Once``, the script will |
| be run, but you will be prometed on a subsequent invocation. Advanced users |
| can add the signer's certificate to the Trusted Publishers of the Computer |
| account to apply to all users (though this technique is out of scope of this |
| document). |
| |
| Alternatively, you may relax the system execution policy to allow running |
| of local scripts without verifying the code signature using the following:: |
| |
| PS C:\> Set-ExecutionPolicy RemoteSigned |
| |
| Since the ``activate.ps1`` script is generated locally for each virtualenv, |
| it is not considered a remote script and can then be executed. |
| |
| .. _`execution policies`: http://technet.microsoft.com/en-us/library/dd347641.aspx |
| |
| The ``--system-site-packages`` Option |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| If you build with ``virtualenv --system-site-packages ENV``, your virtual |
| environment will inherit packages from ``/usr/lib/python2.7/site-packages`` |
| (or wherever your global site-packages directory is). |
| |
| This can be used if you have control over the global site-packages directory, |
| and you want to depend on the packages there. If you want isolation from the |
| global system, do not use this flag. |
| |
| |
| Environment variables and configuration files |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| virtualenv can not only be configured by passing command line options such as |
| ``--distribute`` but also by two other means: |
| |
| - Environment variables |
| |
| Each command line option is automatically used to look for environment |
| variables with the name format ``VIRTUALENV_<UPPER_NAME>``. That means |
| the name of the command line options are capitalized and have dashes |
| (``'-'``) replaced with underscores (``'_'``). |
| |
| For example, to automatically install Distribute instead of setuptools |
| you can also set an environment variable:: |
| |
| $ export VIRTUALENV_DISTRIBUTE=true |
| $ python virtualenv.py ENV |
| |
| It's the same as passing the option to virtualenv directly:: |
| |
| $ python virtualenv.py --distribute ENV |
| |
| This also works for appending command line options, like ``--find-links``. |
| Just leave an empty space between the passsed values, e.g.:: |
| |
| $ export VIRTUALENV_EXTRA_SEARCH_DIR="/path/to/dists /path/to/other/dists" |
| $ virtualenv ENV |
| |
| is the same as calling:: |
| |
| $ python virtualenv.py --extra-search-dir=/path/to/dists --extra-search-dir=/path/to/other/dists ENV |
| |
| - Config files |
| |
| virtualenv also looks for a standard ini config file. On Unix and Mac OS X |
| that's ``$HOME/.virtualenv/virtualenv.ini`` and on Windows, it's |
| ``%APPDATA%\virtualenv\virtualenv.ini``. |
| |
| The names of the settings are derived from the long command line option, |
| e.g. the option ``--distribute`` would look like this:: |
| |
| [virtualenv] |
| distribute = true |
| |
| Appending options like ``--extra-search-dir`` can be written on multiple |
| lines:: |
| |
| [virtualenv] |
| extra-search-dir = |
| /path/to/dists |
| /path/to/other/dists |
| |
| Please have a look at the output of ``virtualenv --help`` for a full list |
| of supported options. |
| |
| Windows Notes |
| ~~~~~~~~~~~~~ |
| |
| Some paths within the virtualenv are slightly different on Windows: scripts and |
| executables on Windows go in ``ENV\Scripts\`` instead of ``ENV/bin/`` and |
| libraries go in ``ENV\Lib\`` rather than ``ENV/lib/``. |
| |
| To create a virtualenv under a path with spaces in it on Windows, you'll need |
| the `win32api <http://sourceforge.net/projects/pywin32/>`_ library installed. |
| |
| PyPy Support |
| ~~~~~~~~~~~~ |
| |
| Beginning with virtualenv version 1.5 `PyPy <http://pypy.org>`_ is |
| supported. To use PyPy 1.4 or 1.4.1, you need a version of virtualenv >= 1.5. |
| To use PyPy 1.5, you need a version of virtualenv >= 1.6.1. |
| |
| Creating Your Own Bootstrap Scripts |
| ----------------------------------- |
| |
| While this creates an environment, it doesn't put anything into the |
| environment. Developers may find it useful to distribute a script |
| that sets up a particular environment, for example a script that |
| installs a particular web application. |
| |
| To create a script like this, call |
| ``virtualenv.create_bootstrap_script(extra_text)``, and write the |
| result to your new bootstrapping script. Here's the documentation |
| from the docstring: |
| |
| Creates a bootstrap script, which is like this script but with |
| extend_parser, adjust_options, and after_install hooks. |
| |
| This returns a string that (written to disk of course) can be used |
| as a bootstrap script with your own customizations. The script |
| will be the standard virtualenv.py script, with your extra text |
| added (your extra text should be Python code). |
| |
| If you include these functions, they will be called: |
| |
| ``extend_parser(optparse_parser)``: |
| You can add or remove options from the parser here. |
| |
| ``adjust_options(options, args)``: |
| You can change options here, or change the args (if you accept |
| different kinds of arguments, be sure you modify ``args`` so it is |
| only ``[DEST_DIR]``). |
| |
| ``after_install(options, home_dir)``: |
| |
| After everything is installed, this function is called. This |
| is probably the function you are most likely to use. An |
| example would be:: |
| |
| def after_install(options, home_dir): |
| if sys.platform == 'win32': |
| bin = 'Scripts' |
| else: |
| bin = 'bin' |
| subprocess.call([join(home_dir, bin, 'easy_install'), |
| 'MyPackage']) |
| subprocess.call([join(home_dir, bin, 'my-package-script'), |
| 'setup', home_dir]) |
| |
| This example immediately installs a package, and runs a setup |
| script from that package. |
| |
| Bootstrap Example |
| ~~~~~~~~~~~~~~~~~ |
| |
| Here's a more concrete example of how you could use this:: |
| |
| import virtualenv, textwrap |
| output = virtualenv.create_bootstrap_script(textwrap.dedent(""" |
| import os, subprocess |
| def after_install(options, home_dir): |
| etc = join(home_dir, 'etc') |
| if not os.path.exists(etc): |
| os.makedirs(etc) |
| subprocess.call([join(home_dir, 'bin', 'easy_install'), |
| 'BlogApplication']) |
| subprocess.call([join(home_dir, 'bin', 'paster'), |
| 'make-config', 'BlogApplication', |
| join(etc, 'blog.ini')]) |
| subprocess.call([join(home_dir, 'bin', 'paster'), |
| 'setup-app', join(etc, 'blog.ini')]) |
| """)) |
| f = open('blog-bootstrap.py', 'w').write(output) |
| |
| Another example is available `here |
| <https://github.com/socialplanning/fassembler/blob/master/fassembler/create-venv-script.py>`_. |
| |
| |
| Using Virtualenv without ``bin/python`` |
| --------------------------------------- |
| |
| Sometimes you can't or don't want to use the Python interpreter |
| created by the virtualenv. For instance, in a `mod_python |
| <http://www.modpython.org/>`_ or `mod_wsgi <http://www.modwsgi.org/>`_ |
| environment, there is only one interpreter. |
| |
| Luckily, it's easy. You must use the custom Python interpreter to |
| *install* libraries. But to *use* libraries, you just have to be sure |
| the path is correct. A script is available to correct the path. You |
| can setup the environment like:: |
| |
| activate_this = '/path/to/env/bin/activate_this.py' |
| execfile(activate_this, dict(__file__=activate_this)) |
| |
| This will change ``sys.path`` and even change ``sys.prefix``, but also allow |
| you to use an existing interpreter. Items in your environment will show up |
| first on ``sys.path``, before global items. However, global items will |
| always be accessible (as if the ``--system-site-packages`` flag had been used |
| in creating the environment, whether it was or not). Also, this cannot undo |
| the activation of other environments, or modules that have been imported. |
| You shouldn't try to, for instance, activate an environment before a web |
| request; you should activate *one* environment as early as possible, and not |
| do it again in that process. |
| |
| Making Environments Relocatable |
| ------------------------------- |
| |
| Note: this option is somewhat experimental, and there are probably |
| caveats that have not yet been identified. Also this does not |
| currently work on Windows. |
| |
| Normally environments are tied to a specific path. That means that |
| you cannot move an environment around or copy it to another computer. |
| You can fix up an environment to make it relocatable with the |
| command:: |
| |
| $ virtualenv --relocatable ENV |
| |
| This will make some of the files created by setuptools or distribute |
| use relative paths, and will change all the scripts to use ``activate_this.py`` |
| instead of using the location of the Python interpreter to select the |
| environment. |
| |
| **Note:** you must run this after you've installed *any* packages into |
| the environment. If you make an environment relocatable, then |
| install a new package, you must run ``virtualenv --relocatable`` |
| again. |
| |
| Also, this **does not make your packages cross-platform**. You can |
| move the directory around, but it can only be used on other similar |
| computers. Some known environmental differences that can cause |
| incompatibilities: a different version of Python, when one platform |
| uses UCS2 for its internal unicode representation and another uses |
| UCS4 (a compile-time option), obvious platform changes like Windows |
| vs. Linux, or Intel vs. ARM, and if you have libraries that bind to C |
| libraries on the system, if those C libraries are located somewhere |
| different (either different versions, or a different filesystem |
| layout). |
| |
| If you use this flag to create an environment, currently, the |
| ``--system-site-packages`` option will be implied. |
| |
| The ``--extra-search-dir`` option |
| --------------------------------- |
| |
| When it creates a new environment, virtualenv installs either setuptools |
| or distribute, and pip. In normal operation when virtualenv is |
| installed, the bundled version of these packages included in the |
| ``virtualenv_support`` directory is used. When ``virtualenv.py`` is run |
| standalone and ``virtualenv_support`` is not available, the latest |
| releases of these packages are fetched from the `Python Package Index |
| <http://pypi.python.org>`_ (PyPI). |
| |
| As an alternative, you can provide your own versions of setuptools, |
| distribute and/or pip on the filesystem, and tell virtualenv to use |
| those distributions instead of downloading them from the Internet. To |
| use this feature, pass one or more ``--extra-search-dir`` options to |
| virtualenv like this:: |
| |
| $ virtualenv --extra-search-dir=/path/to/distributions ENV |
| |
| The ``/path/to/distributions`` path should point to a directory that |
| contains setuptools, distribute and/or pip distributions. Setuptools |
| distributions must be ``.egg`` files; pip distributions should be |
| `.tar.gz` source distributions, and distribute distributions may be |
| either (if found an egg will be used preferentially). |
| |
| Virtualenv will still download these packages if no satisfactory local |
| distributions are found. |
| |
| If you are really concerned about virtualenv fetching these packages |
| from the Internet and want to ensure that it never will, you can also |
| provide an option ``--never-download`` like so:: |
| |
| $ virtualenv --extra-search-dir=/path/to/distributions --never-download ENV |
| |
| If this option is provided, virtualenv will never try to download |
| setuptools/distribute or pip. Instead, it will exit with status code 1 |
| if it fails to find local distributions for any of these required |
| packages. The local distribution lookup is done in the following |
| locations, with the most recent version found used: |
| |
| #. The current directory. |
| #. The directory where virtualenv.py is located. |
| #. A ``virtualenv_support`` directory relative to the directory where |
| virtualenv.py is located. |
| #. If the file being executed is not named virtualenv.py (i.e. is a boot |
| script), a ``virtualenv_support`` directory relative to wherever |
| virtualenv.py is actually installed. |
| |
| |
| Compare & Contrast with Alternatives |
| ------------------------------------ |
| |
| There are several alternatives that create isolated environments: |
| |
| * ``workingenv`` (which I do not suggest you use anymore) is the |
| predecessor to this library. It used the main Python interpreter, |
| but relied on setting ``$PYTHONPATH`` to activate the environment. |
| This causes problems when running Python scripts that aren't part of |
| the environment (e.g., a globally installed ``hg`` or ``bzr``). It |
| also conflicted a lot with Setuptools. |
| |
| * `virtual-python |
| <http://peak.telecommunity.com/DevCenter/EasyInstall#creating-a-virtual-python>`_ |
| is also a predecessor to this library. It uses only symlinks, so it |
| couldn't work on Windows. It also symlinks over the *entire* |
| standard library and global ``site-packages``. As a result, it |
| won't see new additions to the global ``site-packages``. |
| |
| This script only symlinks a small portion of the standard library |
| into the environment, and so on Windows it is feasible to simply |
| copy these files over. Also, it creates a new/empty |
| ``site-packages`` and also adds the global ``site-packages`` to the |
| path, so updates are tracked separately. This script also installs |
| Setuptools automatically, saving a step and avoiding the need for |
| network access. |
| |
| * `zc.buildout <http://pypi.python.org/pypi/zc.buildout>`_ doesn't |
| create an isolated Python environment in the same style, but |
| achieves similar results through a declarative config file that sets |
| up scripts with very particular packages. As a declarative system, |
| it is somewhat easier to repeat and manage, but more difficult to |
| experiment with. ``zc.buildout`` includes the ability to setup |
| non-Python systems (e.g., a database server or an Apache instance). |
| |
| I *strongly* recommend anyone doing application development or |
| deployment use one of these tools. |
| |
| Contributing |
| ------------ |
| |
| Refer to the `contributing to pip`_ documentation - it applies equally to |
| virtualenv, except that virtualenv issues should filed on the `virtualenv |
| repo`_ at GitHub. |
| |
| Virtualenv's release schedule is tied to pip's -- each time there's a new pip |
| release, there will be a new virtualenv release that bundles the new version of |
| pip. |
| |
| Files in the `virtualenv_embedded/` subdirectory are embedded into |
| `virtualenv.py` itself as base64-encoded strings (in order to support |
| single-file use of `virtualenv.py` without installing it). If your patch |
| changes any file in `virtualenv_embedded/`, run `bin/rebuild-script.py` to |
| update the embedded version of that file in `virtualenv.py`; commit that and |
| submit it as part of your patch / pull request. |
| |
| .. _contributing to pip: http://www.pip-installer.org/en/latest/contributing.html |
| .. _virtualenv repo: https://github.com/pypa/virtualenv/ |
| |
| Running the tests |
| ~~~~~~~~~~~~~~~~~ |
| |
| Virtualenv's test suite is small and not yet at all comprehensive, but we aim |
| to grow it. |
| |
| The easy way to run tests (handles test dependencies automatically):: |
| |
| $ python setup.py test |
| |
| If you want to run only a selection of the tests, you'll need to run them |
| directly with nose instead. Create a virtualenv, and install required |
| packages:: |
| |
| $ pip install nose mock |
| |
| Run nosetests:: |
| |
| $ nosetests |
| |
| Or select just a single test file to run:: |
| |
| $ nosetests tests.test_virtualenv |
| |
| |
| Other Documentation and Links |
| ----------------------------- |
| |
| * James Gardner has written a tutorial on using `virtualenv with |
| Pylons |
| <http://wiki.pylonshq.com/display/pylonscookbook/Using+a+Virtualenv+Sandbox>`_. |
| |
| * `Blog announcement |
| <http://blog.ianbicking.org/2007/10/10/workingenv-is-dead-long-live-virtualenv/>`_. |
| |
| * Doug Hellmann wrote a description of his `command-line work flow |
| using virtualenv (virtualenvwrapper) |
| <http://www.doughellmann.com/articles/CompletelyDifferent-2008-05-virtualenvwrapper/index.html>`_ |
| including some handy scripts to make working with multiple |
| environments easier. He also wrote `an example of using virtualenv |
| to try IPython |
| <http://www.doughellmann.com/articles/CompletelyDifferent-2008-02-ipython-and-virtualenv/index.html>`_. |
| |
| * Chris Perkins created a `showmedo video including virtualenv |
| <http://showmedo.com/videos/video?name=2910000&fromSeriesID=291>`_. |
| |
| * `Using virtualenv with mod_wsgi |
| <http://code.google.com/p/modwsgi/wiki/VirtualEnvironments>`_. |
| |
| * `virtualenv commands |
| <https://github.com/thisismedium/virtualenv-commands>`_ for some more |
| workflow-related tools around virtualenv. |
| |
| Status and License |
| ------------------ |
| |
| ``virtualenv`` is a successor to `workingenv |
| <http://cheeseshop.python.org/pypi/workingenv.py>`_, and an extension |
| of `virtual-python |
| <http://peak.telecommunity.com/DevCenter/EasyInstall#creating-a-virtual-python>`_. |
| |
| It was written by Ian Bicking, sponsored by the `Open Planning |
| Project <http://openplans.org>`_ and is now maintained by a |
| `group of developers <https://github.com/pypa/virtualenv/raw/master/AUTHORS.txt>`_. |
| It is licensed under an |
| `MIT-style permissive license <https://github.com/pypa/virtualenv/raw/master/LICENSE.txt>`_. |