python -m venv /path/to/new/virtual/environment

  PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

The :class:`EnvBuilder` class accepts the following keyword arguments on
instantiation:

* *system_site_packages* -- a boolean value indicating that the system Python
  site-packages should be available to the environment (defaults to ``False``).

* *clear* -- a boolean value which, if true, will delete the contents of
  any existing target directory, before creating the environment.

* *symlinks* -- a boolean value indicating whether to attempt to symlink the
  Python binary rather than copying.

* *upgrade* -- a boolean value which, if true, will upgrade an existing
  environment with the running Python - for use when that Python has been
  upgraded in-place (defaults to ``False``).

* *with_pip* -- a boolean value which, if true, ensures pip is
  installed in the virtual environment. This uses :mod:`ensurepip` with
  the ``--default-pip`` option.

* *prompt* -- a string to be used after virtual environment is activated
  (defaults to ``None`` which means directory name of the environment would
  be used). If the special string ``"."`` is provided, the basename of the
  current directory is used as the prompt.

* *upgrade_deps* -- Update the base venv modules to the latest on PyPI

* *scm_ignore_files* -- Create ignore files based for the specified source
  control managers (SCM) in the iterable. Support is defined by having a
  method named ``create_{scm}_ignore_file``. The only value supported by
  default is ``"git"`` via :meth:`create_git_ignore_file`.


.. versionchanged:: 3.4
   Added the ``with_pip`` parameter

.. versionchanged:: 3.6
   Added the ``prompt`` parameter

.. versionchanged:: 3.9
   Added the ``upgrade_deps`` parameter

.. versionchanged:: 3.13
   Added the ``scm_ignore_files`` parameter

:class:`EnvBuilder` may be used as a base class.

.. method:: create(env_dir)

    Create a virtual environment by specifying the target directory
    (absolute or relative to the current directory) which is to contain the
    virtual environment.  The ``create`` method will either create the
    environment in the specified directory, or raise an appropriate
    exception.

    The ``create`` method of the :class:`EnvBuilder` class illustrates the
    hooks available for subclass customization::

        def create(self, env_dir):
            """
            Create a virtualized Python environment in a directory.
            env_dir is the target directory to create an environment in.
            """
            env_dir = os.path.abspath(env_dir)
            context = self.ensure_directories(env_dir)
            self.create_configuration(context)
            self.setup_python(context)
            self.setup_scripts(context)
            self.post_setup(context)

    Each of the methods :meth:`ensure_directories`,
    :meth:`create_configuration`, :meth:`setup_python`,
    :meth:`setup_scripts` and :meth:`post_setup` can be overridden.

.. method:: ensure_directories(env_dir)

    Creates the environment directory and all necessary subdirectories that
    don't already exist, and returns a context object.  This context object
    is just a holder for attributes (such as paths) for use by the other
    methods.  If the :class:`EnvBuilder` is created with the arg
    ``clear=True``, contents of the environment directory will be cleared
    and then all necessary subdirectories will be recreated.

    The returned context object is a :class:`types.SimpleNamespace` with the
    following attributes:

    * ``env_dir`` - The location of the virtual environment. Used for
      ``__VENV_DIR__`` in activation scripts (see :meth:`install_scripts`).

    * ``env_name`` - The name of the virtual environment. Used for
      ``__VENV_NAME__`` in activation scripts (see :meth:`install_scripts`).

    * ``prompt`` - The prompt to be used by the activation scripts. Used for
      ``__VENV_PROMPT__`` in activation scripts (see :meth:`install_scripts`).

    * ``executable`` - The underlying Python executable used by the virtual
      environment. This takes into account the case where a virtual environment
      is created from another virtual environment.

    * ``inc_path`` - The include path for the virtual environment.

    * ``lib_path`` - The purelib path for the virtual environment.

    * ``platlib_path`` - The platlib path for the virtual environment.

    * ``bin_path`` - The script path for the virtual environment.

    * ``bin_name`` - The name of the script path relative to the virtual
      environment location. Used for ``__VENV_BIN_NAME__`` in activation
      scripts (see :meth:`install_scripts`).

    * ``env_exe`` - The name of the Python interpreter in the virtual
      environment. Used for ``__VENV_PYTHON__`` in activation scripts
      (see :meth:`install_scripts`).

    * ``env_exec_cmd`` - The name of the Python interpreter, taking into
      account filesystem redirections. This can be used to run Python in
      the virtual environment.


    .. versionchanged:: 3.11
       The *venv*
       :ref:`sysconfig installation scheme <installation_paths>`
       is used to construct the paths of the created directories.

    .. versionchanged:: 3.12
       The attribute ``lib_path`` was added to the context, and the context
       object was documented.

    .. versionchanged:: 3.15
       The attribute ``platlib_path`` was added to the context.

.. method:: create_configuration(context)

    Creates the ``pyvenv.cfg`` configuration file in the environment.

.. method:: setup_python(context)

    Creates a copy or symlink to the Python executable in the environment.
    On POSIX systems, if a specific executable ``python3.x`` was used,
    symlinks to ``python`` and ``python3`` will be created pointing to that
    executable, unless files with those names already exist.

.. method:: setup_scripts(context)

    Installs activation scripts appropriate to the platform into the virtual
    environment.

.. method:: upgrade_dependencies(context)

   Upgrades the core venv dependency packages (currently :pypi:`pip`)
   in the environment. This is done by shelling out to the
   ``pip`` executable in the environment.

   .. versionadded:: 3.9
   .. versionchanged:: 3.12

      :pypi:`setuptools` is no longer a core venv dependency.

.. method:: post_setup(context)

    A placeholder method which can be overridden in third party
    implementations to pre-install packages in the virtual environment or
    perform other post-creation steps.

.. method:: install_scripts(context, path)

    This method can be
    called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to
    assist in installing custom scripts into the virtual environment.

    *path* is the path to a directory that 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 :data:`os.name` are copied after some text
    replacement of placeholders:

    * ``__VENV_DIR__`` is replaced with the absolute path of the environment
      directory.

    * ``__VENV_NAME__`` is replaced with the environment name (final path
      segment of environment directory).

    * ``__VENV_PROMPT__`` is replaced with the prompt (the environment
      name surrounded by parentheses and with a following space)

    * ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory
      (either ``bin`` or ``Scripts``).

    * ``__VENV_PYTHON__`` is replaced with the absolute path of the
      environment's executable.

    The directories are allowed to exist (for when an existing environment
    is being upgraded).

.. method:: create_git_ignore_file(context)

   Creates a ``.gitignore`` file within the virtual environment that causes
   the entire directory to be ignored by the Git source control manager.

   .. versionadded:: 3.13

.. versionchanged:: 3.7.2
   Windows now uses redirector scripts for ``python[w].exe`` instead of
   copying the actual binaries. In 3.7.2 only :meth:`setup_python` does
   nothing unless running from a build in the source tree.

.. versionchanged:: 3.7.3
   Windows copies the redirector scripts as part of :meth:`setup_python`
   instead of :meth:`setup_scripts`. This was not the case in 3.7.2.
   When using symlinks, the original executables will be linked.

Create an :class:`EnvBuilder` with the given keyword arguments, and call its
:meth:`~EnvBuilder.create` method with the *env_dir* argument.

.. versionadded:: 3.3

.. versionchanged:: 3.4
   Added the *with_pip* parameter

.. versionchanged:: 3.6
   Added the *prompt* parameter

.. versionchanged:: 3.9
   Added the *upgrade_deps* parameter

.. versionchanged:: 3.13
   Added the *scm_ignore_files* parameter

import os
import os.path
from subprocess import Popen, PIPE
import sys
from threading import Thread
from urllib.parse import urlsplit
from urllib.request import urlretrieve
import venv

class ExtendedEnvBuilder(venv.EnvBuilder):
    """
    This builder installs setuptools and pip so that you can pip or
    easy_install other packages into the created virtual environment.

    :param nodist: If true, setuptools and pip are not installed into the
                   created virtual environment.
    :param nopip: If true, pip is not installed into the created
                  virtual environment.
    :param progress: If setuptools or pip are installed, the progress of the
                     installation can be monitored by passing a progress
                     callable. If specified, it is called with two
                     arguments: a string indicating some progress, and a
                     context indicating where the string is coming from.
                     The context argument can have one of three values:
                     'main', indicating that it is called from virtualize()
                     itself, and 'stdout' and 'stderr', which are obtained
                     by reading lines from the output streams of a subprocess
                     which is used to install the app.

                     If a callable is not specified, default progress
                     information is output to sys.stderr.
    """

    def __init__(self, *args, **kwargs):
        self.nodist = kwargs.pop('nodist', False)
        self.nopip = kwargs.pop('nopip', False)
        self.progress = kwargs.pop('progress', None)
        self.verbose = kwargs.pop('verbose', False)
        super().__init__(*args, **kwargs)

    def post_setup(self, context):
        """
        Set up any packages which need to be pre-installed into the
        virtual environment being created.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        os.environ['VIRTUAL_ENV'] = context.env_dir
        if not self.nodist:
            self.install_setuptools(context)
        # Can't install pip without setuptools
        if not self.nopip and not self.nodist:
            self.install_pip(context)

    def reader(self, stream, context):
        """
        Read lines from a subprocess' output stream and either pass to a progress
        callable (if specified) or write progress information to sys.stderr.
        """
        progress = self.progress
        while True:
            s = stream.readline()
            if not s:
                break
            if progress is not None:
                progress(s, context)
            else:
                if not self.verbose:
                    sys.stderr.write('.')
                else:
                    sys.stderr.write(s.decode('utf-8'))
                sys.stderr.flush()
        stream.close()

    def install_script(self, context, name, url):
        _, _, path, _, _ = urlsplit(url)
        fn = os.path.split(path)[-1]
        binpath = context.bin_path
        distpath = os.path.join(binpath, fn)
        # Download script into the virtual environment's binaries folder
        urlretrieve(url, distpath)
        progress = self.progress
        if self.verbose:
            term = '\n'
        else:
            term = ''
        if progress is not None:
            progress('Installing %s ...%s' % (name, term), 'main')
        else:
            sys.stderr.write('Installing %s ...%s' % (name, term))
            sys.stderr.flush()
        # Install in the virtual environment
        args = [context.env_exe, fn]
        p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)
        t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))
        t1.start()
        t2 = Thread(target=self.reader, args=(p.stderr, 'stderr'))
        t2.start()
        p.wait()
        t1.join()
        t2.join()
        if progress is not None:
            progress('done.', 'main')
        else:
            sys.stderr.write('done.\n')
        # Clean up - no longer needed
        os.unlink(distpath)

    def install_setuptools(self, context):
        """
        Install setuptools in the virtual environment.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        url = "https://bootstrap.pypa.io/ez_setup.py"
        self.install_script(context, 'setuptools', url)
        # clear up the setuptools archive which gets downloaded
        pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz')
        files = filter(pred, os.listdir(context.bin_path))
        for f in files:
            f = os.path.join(context.bin_path, f)
            os.unlink(f)

    def install_pip(self, context):
        """
        Install pip in the virtual environment.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        url = 'https://bootstrap.pypa.io/get-pip.py'
        self.install_script(context, 'pip', url)


def main(args=None):
    import argparse

    parser = argparse.ArgumentParser(prog=__name__,
                                     description='Creates virtual Python '
                                                 'environments in one or '
                                                 'more target '
                                                 'directories.')
    parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',
                        help='A directory in which to create the '
                             'virtual environment.')
    parser.add_argument('--no-setuptools', default=False,
                        action='store_true', dest='nodist',
                        help="Don't install setuptools or pip in the "
                             "virtual environment.")
    parser.add_argument('--no-pip', default=False,
                        action='store_true', dest='nopip',
                        help="Don't install pip in the virtual "
                             "environment.")
    parser.add_argument('--system-site-packages', default=False,
                        action='store_true', dest='system_site',
                        help='Give the virtual environment access to the '
                             'system site-packages dir.')
    if os.name == 'nt':
        use_symlinks = False
    else:
        use_symlinks = True
    parser.add_argument('--symlinks', default=use_symlinks,
                        action='store_true', dest='symlinks',
                        help='Try to use symlinks rather than copies, '
                             'when symlinks are not the default for '
                             'the platform.')
    parser.add_argument('--clear', default=False, action='store_true',
                        dest='clear', help='Delete the contents of the '
                                           'virtual environment '
                                           'directory if it already '
                                           'exists, before virtual '
                                           'environment creation.')
    parser.add_argument('--upgrade', default=False, action='store_true',
                        dest='upgrade', help='Upgrade the virtual '
                                             'environment directory to '
                                             'use this version of '
                                             'Python, assuming Python '
                                             'has been upgraded '
                                             'in-place.')
    parser.add_argument('--verbose', default=False, action='store_true',
                        dest='verbose', help='Display the output '
                                             'from the scripts which '
                                             'install setuptools and pip.')
    options = parser.parse_args(args)
    if options.upgrade and options.clear:
        raise ValueError('you cannot supply --upgrade and --clear together.')
    builder = ExtendedEnvBuilder(system_site_packages=options.system_site,
                                   clear=options.clear,
                                   symlinks=options.symlinks,
                                   upgrade=options.upgrade,
                                   nodist=options.nodist,
                                   nopip=options.nopip,
                                   verbose=options.verbose)
    for d in options.dirs:
        builder.create(d)

if __name__ == '__main__':
    rc = 1
    try:
        main()
        rc = 0
    except Exception as e:
        print('Error: %s' % e, file=sys.stderr)
    sys.exit(rc)