| OLD | NEW |
|---|
| (Empty) |
| 1 User Guide | |
| 2 ========== | |
| 3 | |
| 4 | |
| 5 Usage | |
| 6 ----- | |
| 7 | |
| 8 Virtualenv has one basic command:: | |
| 9 | |
| 10 $ virtualenv ENV | |
| 11 | |
| 12 Where ``ENV`` is a directory to place the new virtual environment. It has | |
| 13 a number of usual effects (modifiable by many :ref:`options`): | |
| 14 | |
| 15 - :file:`ENV/lib/` and :file:`ENV/include/` are created, containing supporting | |
| 16 library files for a new virtualenv python. Packages installed in this | |
| 17 environment will live under :file:`ENV/lib/pythonX.X/site-packages/`. | |
| 18 | |
| 19 - :file:`ENV/bin` is created, where executables live - noticeably a new | |
| 20 :command:`python`. Thus running a script with ``#! /path/to/ENV/bin/python`` | |
| 21 would run that script under this virtualenv's python. | |
| 22 | |
| 23 - The crucial packages pip_ and setuptools_ are installed, which allow other | |
| 24 packages to be easily installed to the environment. This associated pip | |
| 25 can be run from :file:`ENV/bin/pip`. | |
| 26 | |
| 27 The python in your new virtualenv is effectively isolated from the python that | |
| 28 was used to create it. | |
| 29 | |
| 30 .. _pip: https://pypi.python.org/pypi/pip | |
| 31 .. _setuptools: https://pypi.python.org/pypi/setuptools | |
| 32 | |
| 33 | |
| 34 .. _activate: | |
| 35 | |
| 36 activate script | |
| 37 ~~~~~~~~~~~~~~~ | |
| 38 | |
| 39 In a newly created virtualenv there will also be a :command:`activate` shell | |
| 40 script. For Windows systems, activation scripts are provided for | |
| 41 the Command Prompt and Powershell. | |
| 42 | |
| 43 On Posix systems, this resides in :file:`/ENV/bin/`, so you can run:: | |
| 44 | |
| 45 $ source bin/activate | |
| 46 | |
| 47 For some shells (e.g. the original Bourne Shell) you may need to use the | |
| 48 :command:`.` command, when :command:`source` does not exist. | |
| 49 | |
| 50 This will change your ``$PATH`` so its first entry is the virtualenv's | |
| 51 ``bin/`` directory. (You have to use ``source`` because it changes your | |
| 52 shell environment in-place.) This is all it does; it's purely a | |
| 53 convenience. If you directly run a script or the python interpreter | |
| 54 from the virtualenv's ``bin/`` directory (e.g. ``path/to/ENV/bin/pip`` | |
| 55 or ``/path/to/ENV/bin/python-script.py``) there's no need for | |
| 56 activation. | |
| 57 | |
| 58 The ``activate`` script will also modify your shell prompt to indicate | |
| 59 which environment is currently active. To disable this behaviour, see | |
| 60 :envvar:`VIRTUAL_ENV_DISABLE_PROMPT`. | |
| 61 | |
| 62 To undo these changes to your path (and prompt), just run:: | |
| 63 | |
| 64 $ deactivate | |
| 65 | |
| 66 On Windows, the equivalent `activate` script is in the ``Scripts`` folder:: | |
| 67 | |
| 68 > \path\to\env\Scripts\activate | |
| 69 | |
| 70 And type ``deactivate`` to undo the changes. | |
| 71 | |
| 72 Based on your active shell (CMD.exe or Powershell.exe), Windows will use | |
| 73 either activate.bat or activate.ps1 (as appropriate) to activate the | |
| 74 virtual environment. If using Powershell, see the notes about code signing | |
| 75 below. | |
| 76 | |
| 77 .. note:: | |
| 78 | |
| 79 If using Powershell, the ``activate`` script is subject to the | |
| 80 `execution policies`_ on the system. By default on Windows 7, the system's | |
| 81 excution policy is set to ``Restricted``, meaning no scripts like the | |
| 82 ``activate`` script are allowed to be executed. But that can't stop us | |
| 83 from changing that slightly to allow it to be executed. | |
| 84 | |
| 85 In order to use the script, you can relax your system's execution | |
| 86 policy to ``AllSigned``, meaning all scripts on the system must be | |
| 87 digitally signed to be executed. Since the virtualenv activation | |
| 88 script is signed by one of the authors (Jannis Leidel) this level of | |
| 89 the execution policy suffices. As an administrator run:: | |
| 90 | |
| 91 PS C:\> Set-ExecutionPolicy AllSigned | |
| 92 | |
| 93 Then you'll be asked to trust the signer, when executing the script. | |
| 94 You will be prompted with the following:: | |
| 95 | |
| 96 PS C:\> virtualenv .\foo | |
| 97 New python executable in C:\foo\Scripts\python.exe | |
| 98 Installing setuptools................done. | |
| 99 Installing pip...................done. | |
| 100 PS C:\> .\foo\scripts\activate | |
| 101 | |
| 102 Do you want to run software from this untrusted publisher? | |
| 103 File C:\foo\scripts\activate.ps1 is published by E=jannis@leidel.info, | |
| 104 CN=Jannis Leidel, L=Berlin, S=Berlin, C=DE, Description=581796-Gh7xfJxkx
QSIO4E0 | |
| 105 and is not trusted on your system. Only run scripts from trusted publish
ers. | |
| 106 [V] Never run [D] Do not run [R] Run once [A] Always run [?] Help | |
| 107 (default is "D"):A | |
| 108 (foo) PS C:\> | |
| 109 | |
| 110 If you select ``[A] Always Run``, the certificate will be added to the | |
| 111 Trusted Publishers of your user account, and will be trusted in this | |
| 112 user's context henceforth. If you select ``[R] Run Once``, the script will | |
| 113 be run, but you will be prometed on a subsequent invocation. Advanced users | |
| 114 can add the signer's certificate to the Trusted Publishers of the Computer | |
| 115 account to apply to all users (though this technique is out of scope of this | |
| 116 document). | |
| 117 | |
| 118 Alternatively, you may relax the system execution policy to allow running | |
| 119 of local scripts without verifying the code signature using the following:: | |
| 120 | |
| 121 PS C:\> Set-ExecutionPolicy RemoteSigned | |
| 122 | |
| 123 Since the ``activate.ps1`` script is generated locally for each virtualenv, | |
| 124 it is not considered a remote script and can then be executed. | |
| 125 | |
| 126 .. _`execution policies`: http://technet.microsoft.com/en-us/library/dd347641.as
px | |
| 127 | |
| 128 The :option:`--system-site-packages` Option | |
| 129 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 130 | |
| 131 If you build with ``virtualenv --system-site-packages ENV``, your virtual | |
| 132 environment will inherit packages from ``/usr/lib/python2.7/site-packages`` | |
| 133 (or wherever your global site-packages directory is). | |
| 134 | |
| 135 This can be used if you have control over the global site-packages directory, | |
| 136 and you want to depend on the packages there. If you want isolation from the | |
| 137 global system, do not use this flag. | |
| 138 | |
| 139 Windows Notes | |
| 140 ~~~~~~~~~~~~~ | |
| 141 | |
| 142 Some paths within the virtualenv are slightly different on Windows: scripts and | |
| 143 executables on Windows go in ``ENV\Scripts\`` instead of ``ENV/bin/`` and | |
| 144 libraries go in ``ENV\Lib\`` rather than ``ENV/lib/``. | |
| 145 | |
| 146 To create a virtualenv under a path with spaces in it on Windows, you'll need | |
| 147 the `win32api <http://sourceforge.net/projects/pywin32/>`_ library installed. | |
| 148 | |
| 149 | |
| 150 Using Virtualenv without ``bin/python`` | |
| 151 --------------------------------------- | |
| 152 | |
| 153 Sometimes you can't or don't want to use the Python interpreter | |
| 154 created by the virtualenv. For instance, in a `mod_python | |
| 155 <http://www.modpython.org/>`_ or `mod_wsgi <http://www.modwsgi.org/>`_ | |
| 156 environment, there is only one interpreter. | |
| 157 | |
| 158 Luckily, it's easy. You must use the custom Python interpreter to | |
| 159 *install* libraries. But to *use* libraries, you just have to be sure | |
| 160 the path is correct. A script is available to correct the path. You | |
| 161 can setup the environment like:: | |
| 162 | |
| 163 activate_this = '/path/to/env/bin/activate_this.py' | |
| 164 execfile(activate_this, dict(__file__=activate_this)) | |
| 165 | |
| 166 This will change ``sys.path`` and even change ``sys.prefix``, but also allow | |
| 167 you to use an existing interpreter. Items in your environment will show up | |
| 168 first on ``sys.path``, before global items. However, global items will | |
| 169 always be accessible (as if the :option:`--system-site-packages` flag had been | |
| 170 used in creating the environment, whether it was or not). Also, this cannot undo | |
| 171 the activation of other environments, or modules that have been imported. | |
| 172 You shouldn't try to, for instance, activate an environment before a web | |
| 173 request; you should activate *one* environment as early as possible, and not | |
| 174 do it again in that process. | |
| 175 | |
| 176 Making Environments Relocatable | |
| 177 ------------------------------- | |
| 178 | |
| 179 **Note:** this option is somewhat experimental, and there are probably | |
| 180 caveats that have not yet been identified. | |
| 181 | |
| 182 .. warning:: | |
| 183 | |
| 184 The ``--relocatable`` option currently has a number of issues, | |
| 185 and is not guaranteed to work in all circumstances. It is possible | |
| 186 that the option will be deprecated in a future version of ``virtualenv``. | |
| 187 | |
| 188 Normally environments are tied to a specific path. That means that | |
| 189 you cannot move an environment around or copy it to another computer. | |
| 190 You can fix up an environment to make it relocatable with the | |
| 191 command:: | |
| 192 | |
| 193 $ virtualenv --relocatable ENV | |
| 194 | |
| 195 This will make some of the files created by setuptools use relative paths, | |
| 196 and will change all the scripts to use ``activate_this.py`` instead of using | |
| 197 the location of the Python interpreter to select the environment. | |
| 198 | |
| 199 **Note:** scripts which have been made relocatable will only work if | |
| 200 the virtualenv is activated, specifically the python executable from | |
| 201 the virtualenv must be the first one on the system PATH. Also note that | |
| 202 the activate scripts are not currently made relocatable by | |
| 203 ``virtualenv --relocatable``. | |
| 204 | |
| 205 **Note:** you must run this after you've installed *any* packages into | |
| 206 the environment. If you make an environment relocatable, then | |
| 207 install a new package, you must run ``virtualenv --relocatable`` | |
| 208 again. | |
| 209 | |
| 210 Also, this **does not make your packages cross-platform**. You can | |
| 211 move the directory around, but it can only be used on other similar | |
| 212 computers. Some known environmental differences that can cause | |
| 213 incompatibilities: a different version of Python, when one platform | |
| 214 uses UCS2 for its internal unicode representation and another uses | |
| 215 UCS4 (a compile-time option), obvious platform changes like Windows | |
| 216 vs. Linux, or Intel vs. ARM, and if you have libraries that bind to C | |
| 217 libraries on the system, if those C libraries are located somewhere | |
| 218 different (either different versions, or a different filesystem | |
| 219 layout). | |
| 220 | |
| 221 If you use this flag to create an environment, currently, the | |
| 222 :option:`--system-site-packages` option will be implied. | |
| 223 | |
| 224 The :option:`--extra-search-dir` option | |
| 225 --------------------------------------- | |
| 226 | |
| 227 This option allows you to provide your own versions of setuptools and/or | |
| 228 pip to use instead of the embedded versions that come with virtualenv. | |
| 229 | |
| 230 To use this feature, pass one or more ``--extra-search-dir`` options to | |
| 231 virtualenv like this:: | |
| 232 | |
| 233 $ virtualenv --extra-search-dir=/path/to/distributions ENV | |
| 234 | |
| 235 The ``/path/to/distributions`` path should point to a directory that contains | |
| 236 setuptools and/or pip wheels. | |
| 237 | |
| 238 virtualenv will look for wheels in the specified directories, but will use | |
| 239 pip's standard algorithm for selecting the wheel to install, which looks for | |
| 240 the latest compatible wheel. | |
| 241 | |
| 242 As well as the extra directories, the search order includes: | |
| 243 | |
| 244 #. The ``virtualenv_support`` directory relative to virtualenv.py | |
| 245 #. The directory where virtualenv.py is located. | |
| 246 #. The current directory. | |
| 247 | |
| 248 If no satisfactory local distributions are found, virtualenv will | |
| 249 fail. Virtualenv will never download packages. | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 1407953011:
Re-land: Removed virtualenv from depot_tools (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/tools/depot_tools