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
The command, if run with -h, will show the available options:
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.
3.4 版更變: Installs pip by default, added the --without-pip and --copies
options
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.
The created pyvenv.cfg file also includes the
include-system-site-packages key, set to true if venv is
run with the --system-site-packages option, false otherwise.
Unless the --without-pip option is given, ensurepip will be
invoked to bootstrap pip into the virtual environment.
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:
| Platform | Shell | Command to activate virtual environment |
|---|---|---|
| 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.
3.4 版新加入: fish and csh activation scripts.