5. Additional Tools and Scripts

5.1. pyvenv - Creating virtual environments

Creation of virtual environments is done by executing the pyvenv script:

pyvenv /path/to/new/virtual/environment

Running this command creates the target directory (creating any parent directories that don’t exist already) and places a pyvenv.cfg file in it with a home key pointing to the Python installation the command was run from. It also creates a bin (or Scripts on Windows) subdirectory containing a copy of the python binary (or binaries, in the case of Windows). It also creates an (initially empty) lib/pythonX.Y/site-packages subdirectory (on Windows, this is Lib\site-packages).

On Windows, you may have to invoke the pyvenv script as follows, if you don’t have the relevant PATH and PATHEXT settings:

c:\Temp>c:\Python35\python c:\Python35\Tools\Scripts\pyvenv.py myenv

or equivalently:

c:\Temp>c:\Python35\python -m venv myenv

La commande, si lancée avec -h, montrera les options disponibles :

usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
            [--upgrade] [--without-pip]
            ENV_DIR [ENV_DIR ...]

Creates virtual Python environments in one or more target directories.

positional arguments:
  ENV_DIR             A directory to create the environment in.

optional arguments:
  -h, --help             show this help message and exit
  --system-site-packages Give the virtual environment access to the system
                         site-packages dir.
  --symlinks             Try to use symlinks rather than copies, when symlinks
                         are not the default for the platform.
  --copies               Try to use copies rather than symlinks, even when
                         symlinks are the default for the platform.
  --clear                Delete the contents of the environment directory if it
                         already exists, before environment creation.
  --upgrade              Upgrade the environment directory to use this version
                         of Python, assuming Python has been upgraded in-place.
  --without-pip          Skips installing or upgrading pip in the virtual
                         environment (pip is bootstrapped by default)

Depending on how the venv functionality has been invoked, the usage message may vary slightly, e.g. referencing pyvenv rather than venv.

Modifié dans la version 3.4: Installe pip par défaut, ajout des options --without-pip et --copies

Modifié dans la version 3.4: In earlier versions, if the target directory already existed, an error was raised, unless the --clear or --upgrade option was provided. Now, if an existing directory is specified, its contents are removed and the directory is processed as if it had been newly created.

Le fichier crée pyenv.cfg inclus aussi la clé include-system-site-packages, dont la valeur est true si venv est lancé avec l’option --system-site-packages, sinon sa valeur est false.

Sauf si l’option --without-pip est incluse, ensurepip sera invoqué pour amorcer pip dans l’environnement virtuel.

Multiple paths can be given to pyvenv, in which case an identical virtualenv will be created, according to the given options, at each provided path.

Once a venv has been created, it can be « activated » using a script in the venv’s binary directory. The invocation of the script is platform-specific:

Plateforme Invite de commande Commande pour activer l’environnement virtuel
Posix bash/zsh $ source <venv>/bin/activate
  fish $ . <venv>/bin/activate.fish
  csh/tcsh $ source <venv>/bin/activate.csh
Windows cmd.exe C:\\{venv}\\Scripts\\activate.bat
  PowerShell PS C:\\> <venv>\\Scripts\\Activate.ps1

You don’t specifically need to activate an environment; activation just prepends the venv’s binary directory to your path, so that « python » invokes the venv’s Python interpreter and you can run installed scripts without having to use their full path. However, all scripts installed in a venv should be runnable without activating it, and run with the venv’s Python automatically.

You can deactivate a venv by typing « deactivate » in your shell. The exact mechanism is platform-specific: for example, the Bash activation script defines a « deactivate » function, whereas on Windows there are separate scripts called deactivate.bat and Deactivate.ps1 which are installed when the venv is created.

Nouveau dans la version 3.4: Les scripts d’activation pour fish et csh.