diff options
Diffstat (limited to 'Doc/tutorial/venv.rst')
| -rw-r--r-- | Doc/tutorial/venv.rst | 111 |
1 files changed, 62 insertions, 49 deletions
diff --git a/Doc/tutorial/venv.rst b/Doc/tutorial/venv.rst index 3b2ee2e24c..e2dd57d48f 100644 --- a/Doc/tutorial/venv.rst +++ b/Doc/tutorial/venv.rst @@ -20,15 +20,14 @@ the requirements of every application. If application A needs version the requirements are in conflict and installing either version 1.0 or 2.0 will leave one application unable to run. -The solution for this problem is to create a :term:`virtual -environment` (often shortened to "virtualenv"), a self-contained -directory tree that contains a Python installation for a particular -version of Python, plus a number of additional packages. +The solution for this problem is to create a :term:`virtual environment`, a +self-contained directory tree that contains a Python installation for a +particular version of Python, plus a number of additional packages. Different applications can then use different virtual environments. To resolve the earlier example of conflicting requirements, application A can have its own virtual environment with version 1.0 -installed while application B has another virtualenv with version 2.0. +installed while application B has another virtual environment with version 2.0. If application B requires a library be upgraded to version 3.0, this will not affect application A's environment. @@ -36,29 +35,26 @@ not affect application A's environment. Creating Virtual Environments ============================= -The script used to create and manage virtual environments is called -:program:`pyvenv`. :program:`pyvenv` will usually install the most -recent version of Python that you have available; the script is also -installed with a version number, so if you have multiple versions of -Python on your system you can select a specific Python version by -running ``pyvenv-3.4`` or whichever version you want. +The module used to create and manage virtual environments is called +:mod:`venv`. :mod:`venv` will usually install the most recent version of +Python that you have available. If you have multiple versions of Python on your +system, you can select a specific Python version by running ``python3`` or +whichever version you want. -To create a virtualenv, decide upon a directory -where you want to place it and run :program:`pyvenv` with the -directory path:: +To create a virtual environment, decide upon a directory where you want to +place it, and run the :mod:`venv` module as a script with the directory path:: - pyvenv tutorial-env + python3 -m venv tutorial-env This will create the ``tutorial-env`` directory if it doesn't exist, and also create directories inside it containing a copy of the Python interpreter, the standard library, and various supporting files. -Once you've created a virtual environment, you need to -activate it. +Once you've created a virtual environment, you may activate it. On Windows, run:: - tutorial-env/Scripts/activate + tutorial-env\Scripts\activate.bat On Unix or MacOS, run:: @@ -69,33 +65,36 @@ On Unix or MacOS, run:: ``activate.csh`` and ``activate.fish`` scripts you should use instead.) -Activating the virtualenv will change your shell's prompt to show what -virtualenv you're using, and modify the environment so that running -``python`` will get you that particular version and installation of -Python. For example:: +Activating the virtual environment will change your shell's prompt to show what +virtual environment you're using, and modify the environment so that running +``python`` will get you that particular version and installation of Python. +For example: - -> source ~/envs/tutorial-env/bin/activate - (tutorial-env) -> python - Python 3.4.3+ (3.4:c7b9645a6f35+, May 22 2015, 09:31:25) +.. code-block:: bash + + $ source ~/envs/tutorial-env/bin/activate + (tutorial-env) $ python + Python 3.5.1 (default, May 6 2016, 10:59:36) ... >>> import sys >>> sys.path - ['', '/usr/local/lib/python34.zip', ..., - '~/envs/tutorial-env/lib/python3.4/site-packages'] + ['', '/usr/local/lib/python35.zip', ..., + '~/envs/tutorial-env/lib/python3.5/site-packages'] >>> Managing Packages with pip ========================== -Once you've activated a virtual environment, you can install, upgrade, -and remove packages using a program called :program:`pip`. By default -``pip`` will install packages from the Python Package Index, -<https://pypi.python.org/pypi>. You can browse the Python Package Index -by going to it in your web browser, or you can use ``pip``'s -limited search feature:: +You can install, upgrade, and remove packages using a program called +:program:`pip`. By default ``pip`` will install packages from the Python +Package Index, <https://pypi.python.org/pypi>. You can browse the Python +Package Index by going to it in your web browser, or you can use ``pip``'s +limited search feature: + +.. code-block:: bash - (tutorial-env) -> pip search astronomy + (tutorial-env) $ pip search astronomy skyfield - Elegant astronomy for Python gary - Galactic astronomy and gravitational dynamics. novas - The United States Naval Observatory NOVAS astronomy library @@ -107,9 +106,11 @@ limited search feature:: "freeze", etc. (Consult the :ref:`installing-index` guide for complete documentation for ``pip``.) -You can install the latest version of a package by specifying a package's name:: +You can install the latest version of a package by specifying a package's name: + +.. code-block:: bash - -> pip install novas + (tutorial-env) $ pip install novas Collecting novas Downloading novas-3.1.1.3.tar.gz (136kB) Installing collected packages: novas @@ -117,9 +118,11 @@ You can install the latest version of a package by specifying a package's name:: Successfully installed novas-3.1.1.3 You can also install a specific version of a package by giving the -package name followed by ``==`` and the version number:: +package name followed by ``==`` and the version number: - -> pip install requests==2.6.0 +.. code-block:: bash + + (tutorial-env) $ pip install requests==2.6.0 Collecting requests==2.6.0 Using cached requests-2.6.0-py2.py3-none-any.whl Installing collected packages: requests @@ -128,9 +131,11 @@ package name followed by ``==`` and the version number:: If you re-run this command, ``pip`` will notice that the requested version is already installed and do nothing. You can supply a different version number to get that version, or you can run ``pip -install --upgrade`` to upgrade the package to the latest version:: +install --upgrade`` to upgrade the package to the latest version: + +.. code-block:: bash - -> pip install --upgrade requests + (tutorial-env) $ pip install --upgrade requests Collecting requests Installing collected packages: requests Found existing installation: requests 2.6.0 @@ -141,9 +146,11 @@ install --upgrade`` to upgrade the package to the latest version:: ``pip uninstall`` followed by one or more package names will remove the packages from the virtual environment. -``pip show`` will display information about a particular package:: +``pip show`` will display information about a particular package: - (tutorial-env) -> pip show requests +.. code-block:: bash + + (tutorial-env) $ pip show requests --- Metadata-Version: 2.0 Name: requests @@ -157,9 +164,11 @@ packages from the virtual environment. Requires: ``pip list`` will display all of the packages installed in the virtual -environment:: +environment: + +.. code-block:: bash - (tutorial-env) -> pip list + (tutorial-env) $ pip list novas (3.1.1.3) numpy (1.9.2) pip (7.0.3) @@ -168,19 +177,23 @@ environment:: ``pip freeze`` will produce a similar list of the installed packages, but the output uses the format that ``pip install`` expects. -A common convention is to put this list in a ``requirements.txt`` file:: +A common convention is to put this list in a ``requirements.txt`` file: - (tutorial-env) -> pip freeze > requirements.txt - (tutorial-env) -> cat requirements.txt +.. code-block:: bash + + (tutorial-env) $ pip freeze > requirements.txt + (tutorial-env) $ cat requirements.txt novas==3.1.1.3 numpy==1.9.2 requests==2.7.0 The ``requirements.txt`` can then be committed to version control and shipped as part of an application. Users can then install all the -necessary packages with ``install -r``:: +necessary packages with ``install -r``: + +.. code-block:: bash - -> pip install -r requirements.txt + (tutorial-env) $ pip install -r requirements.txt Collecting novas==3.1.1.3 (from -r requirements.txt (line 1)) ... Collecting numpy==1.9.2 (from -r requirements.txt (line 2)) |