The command, if run with ``-h``, will show the available options::
- usage: pyvenv [-h] [--
no-distribute] [--no-site-packages] [--clear]
+ usage: pyvenv [-h] [---site-packages] [--clear]
Creates virtual Python environments in one or more target directories.
-h, --help show this help message and exit
- --no-distribute Don't install Distribute in the virtual environment.
--system-site-packages Give access to the global site-packages dir to the
+ --symlink Attempt to symlink rather than copy.
--clear Delete the environment directory if it already exists.
If not specified and the directory exists, an error is
- The current version allows Distribute to be optionally installed within
- environments, so facilitate installation of existing packages and
- experimentation with virtual environments. This functionality will be
- removed from the standard library before the release of Python 3.3: it is
- expected that third-party tools using this module will fill the gap.
If the target directory already exists an error will be raised, unless
the ``--clear`` option was provided, in which case the target
The created ``pyvenv.cfg`` file also includes the
``include-system-site-packages`` key, set to ``true`` if ``venv`` is
-run with the ``--
use-site-packages`` option, ``false`` otherwise.
+run with the ``---site-packages`` option, ``false`` otherwise.
Multiple paths can be given to ``pyvenv``, in which case an identical
virtualenv will be created, according to the given options, at each
existing target directory instead of raising an exception
- * ``
use_symlinks`` - A Boolean value indicating whether to attempt
+ * ``symlinks`` - A Boolean value indicating whether to attempt
to symlink the Python binary (and any necessary DLLs or other
binaries, e.g. ``pythonw.exe``), rather than copying. Defaults to
``True`` on Linux and Unix systems, but ``False`` on Windows and
- system_site_packages=False, clear=False,
+ system_site_packages=False, clear=False, symlinks=e):
- system_site_packages=system_site_packages, clear=clear)
The ``create`` method of the ``EnvBuilder`` class illustrates the
-hooks available for customization::
+hooks available for customization::
def create(self, env_dir):
context = self.create_directories(env_dir)
Each of the methods ``create_directories``, ``create_configuration``,
packages`` and ``setup _scripts`` can be
+``setup_python``, ``setup_s`` and ``setup`` can be
overridden. The functions of these methods are:
* ``create_directories`` - creates the environment directory and
* ``setup_python`` - creates a copy of the Python executable (and,
under Windows, DLLs) in the environment.
- * ``setup_packages`` - A placeholder method which can be overridden
+ * ``setup_scripts`` - Installs activation scripts appropriate to the
+ platform into the virtual environment.
+ * ``post_setup`` - A placeholder method which can be overridden
in third party implementations to pre-install packages in the
+ virtual environment.
- * ``setup_scripts`` - A placeholder methd which can be overridden
- in third party implementations to pre-install scripts (such as
- activation and deactivation scripts) in the virtual environment.
+In addition, ``EnvBuilder`` provides an ``install_scripts`` utility
+method that can be called from ``setup_scripts`` or ``post_setup`` in
+subclasses to assist in installing custom scripts into the virtual
+environment. The method accepts as arguments the context object (see
+above) and a path to a directory. The directory should contain
+subdirectories "common", "posix", "nt", each containing scripts
+destined for the bin directory in the environment. The contents of
+"common" and the directory corresponding to ``os.name`` are copied
+after some text replacement of placeholders:
-The ``DistributeEnvBuilder`` subclass in the reference implementation
-illustrates how these last two methods can be used in practice. It's
-not envisaged that ``DistributeEnvBuilder`` will be actually added to
-Python core, but it makes the reference implementation more
-immediately useful for testing and exploratory purposes.
+* ``__VENV_DIR__`` is replaced with the absolute path of the
- * The ``setup_packages`` method installs Distribute in the target
- environment. This is needed at the moment in order to actually
- install most packages in an environment, since most packages are
- not yet packaging / setup.cfg based.
+* ``__VENV_NAME__`` is replaced with the environment name (final path
+ segment of environment directory).
- * The ``setup_scripts`` method installs activation and pysetup3
- scripts in the environment. This is also done in a configurable
- way: A ``scripts`` property on the builder is expected to provide
- a buffer which is a base64-encoded zip file. The zip file
- contains directories "common", "nt", and "posix", each
- containing scripts destined for the bin directory in the
- environment. The contents of "common" and the directory
- corresponding to the platform are copied after doing some
- text replacement of placeholders:
+* ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory
+ (either ``bin`` or ``Scripts``).
- * ``__VIRTUAL_ENV__`` is replaced with absolute path of the
- * ``__VIRTUAL_PROMPT__`` is replaced with the environment
- * ``__BIN_NAME__`` is replaced with the name of the bin
- * ``__ENV_PYTHON__`` is replaced with the absolute path of the
- environment's executable.
+* ``__VENV_PYTHON__`` is replaced with the absolute path of the
+ environment's executable.