diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 391f230ce..9405e258a 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -223,13 +223,7 @@ Interpreter Tools Virtual Environments -------------------- -A Virtual Environment is a tool to keep the dependencies required by different -projects in separate places, by creating virtual Python environments for them. -It solves the "Project X depends on version 1.x but, Project Y needs 4.x" -dilemma, and keeps your global site-packages directory clean and manageable. - -For example, you can work on a project which requires Django 1.3 while also -maintaining a project which requires Django 1.0. +Virtual Environments provide a powerful way to isolate project package dependencies. This means that you can use packages particular to a Python project without installing them system wide and thus avoiding potential version conflicts. To start using and see more information: `Virtual Environments `_ docs. diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index e7f3d0ed1..cb9a10012 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -25,6 +25,9 @@ Install virtualenv via pip: Basic Usage ~~~~~~~~~~~ +Python 2.x +.......... + 1. Create a virtual environment for a project: .. code-block:: console @@ -79,6 +82,53 @@ installed libraries. To delete a virtual environment, just delete its folder. (In this case, it would be ``rm -rf venv``.) +Python 3.3+ +........... + +The ``venv`` module comes pre-built into Python 3.3 and above. This version is much more flexible since you can extend `EnvBuilder` to make your virtual environments more personalized and powerful. + +1. Create a virtual environment for a project: + +.. code-block:: console + + $ pyenv /path/to/new/venv + +The ``pyvenv`` script will create the target directory and any parent directories that are needed as well. It will place a ``pyvenv.cfg`` file in it and add a ``bin`` (``Scripts`` on Windows) subdirectory which will contain the Python executable files, and a copy of the ``pip`` library which you +can use to install other packages. The name of the virtual environment can be anything (``venv`` in this case); omitting the name will place the files in the current directory instead. + +2. To begin using the virtual environment, it needs to be activated: + +.. code-block:: console + + $ source /path/to/new/venv/bin/activate + +The name of the current virtual environment will now appear on the left of +the prompt (e.g. ``(venv)Your-Computer:your_project UserName$)`` to let you know +that it's active. From now on, any package that you install using pip will be +placed in the ``venv`` folder, isolated from the global Python installation. + +Install packages as usual, for example: + +.. code-block:: console + + $ pip install requests + +All the packages will be installed in :file:`lib/python3.x/site-packages/` + +3. If you are done working in the virtual environment for the moment, you can + deactivate it: + +.. code-block:: console + + $ deactivate + +This puts you back to the system's default Python interpreter with all its +installed libraries. + +To delete a virtual environment, just delete its folder. (In this case, +it would be ``rm -rf venv``.) + + After a while, though, you might end up with a lot of virtual environments littered across your system, and its possible you'll forget their names or where they were placed.