Skip to content

Commit ef6df05

Browse files
sigmavirus24sigmavirus24
committed
Merge pull request realpython#495 from tbarn/master
Combined and centralized virtualenv docs, fixes issue realpython#123
2 parents 3acec12 + 9c7df81 commit ef6df05

5 files changed

Lines changed: 93 additions & 215 deletions

File tree

‎docs/dev/env.rst‎

Lines changed: 9 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -218,113 +218,18 @@ Interpreter Tools
218218
:::::::::::::::::
219219

220220

221-
virtualenv
222-
----------
223-
224-
Virtualenv is a tool to keep the dependencies required by different projects
225-
in separate places, by creating virtual Python environments for them.
226-
It solves the "Project X depends on version 1.x but, Project Y needs 4.x"
227-
dilemma, and keeps your global site-packages directory clean and manageable.
228-
229-
`virtualenv <http://www.virtualenv.org/en/latest/index.html>`_ creates
230-
a folder which contains all the necessary executables to use the
231-
packages that a Python project would need. An example workflow is given
232-
below.
233-
234-
Install virtualenv:
235-
236-
.. code-block:: console
237-
238-
$ pip install virtualenv
239-
240-
241-
Create a virtual environment for a project:
242-
243-
.. code-block:: console
244-
245-
$ cd my_project
246-
$ virtualenv venv
247-
248-
``virtualenv venv`` will create a folder in the current directory
249-
which will contain the Python executable files, and a copy of the ``pip``
250-
library which you can use to install other packages. The name of the
251-
virtual environment (in this case, it was ``venv``) can be anything;
252-
omitting the name will place the files in the current directory instead.
253-
254-
To start using the virtual environment, run:
255-
256-
.. code-block:: console
257-
258-
$ source venv/bin/activate
259-
260-
261-
The name of the current virtual environment will now appear on the left
262-
of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to
263-
let you know that it's active. From now on, any package that you install
264-
using ``pip`` will be placed in the ``venv`` folder, isolated from the global
265-
Python installation.
266-
267-
Install packages as usual:
268-
269-
.. code-block:: console
270-
271-
$ pip install requests
221+
Virtual Environments
222+
--------------------
272223

273-
To stop using an environment, simply type ``deactivate``. To remove the
274-
environment, just remove the directory it was installed into. (In this
275-
case, it would be ``rm -rf venv``.)
276-
277-
Other Notes
278-
^^^^^^^^^^^
279-
280-
Running ``virtualenv`` with the option :option:`--no-site-packages` will not
281-
include the packages that are installed globally. This can be useful
282-
for keeping the package list clean in case it needs to be accessed later.
283-
[This is the default behavior for ``virtualenv`` 1.7 and later.]
284-
285-
In order to keep your environment consistent, it's a good idea to "freeze"
286-
the current state of the environment packages. To do this, run
287-
288-
.. code-block:: console
289-
290-
$ pip freeze > requirements.txt
291-
292-
This will create a :file:`requirements.txt` file, which contains a simple
293-
list of all the packages in the current environment, and their respective
294-
versions. Later it will be easier for a different developer (or you, if you
295-
need to re-create the environment) to install the same packages using the
296-
same versions:
297-
298-
.. code-block:: console
299-
300-
$ pip install -r requirements.txt
301-
302-
This can help ensure consistency across installations, across deployments,
303-
and across developers.
304-
305-
Lastly, remember to exclude the virtual environment folder from source
306-
control by adding it to the ignore list.
307-
308-
virtualenvwrapper
309-
-----------------
310-
311-
`Virtualenvwrapper <http://pypi.python.org/pypi/virtualenvwrapper>`_ makes
312-
virtualenv a pleasure to use by wrapping the command line API with a nicer CLI.
313-
314-
.. code-block:: console
315-
316-
$ pip install virtualenvwrapper
317-
318-
319-
Put this into your :file:`~/.bash_profile` (Linux/Mac) file:
320-
321-
.. code-block:: console
224+
A Virtual Environment is a tool to keep the dependencies required by different projects
225+
in separate places, by creating virtual Python environments for them. It solves the
226+
"Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
227+
your global site-packages directory clean and manageable.
322228

323-
$ export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
229+
For example, you can work on a project which requires Django 1.3 while also
230+
maintaining a project which requires Django 1.0.
324231

325-
This will prevent your virtualenvs from relying on your (global) site packages
326-
directory, so that they are completely separate.
327-
[Note: This is the default behavior for ``virtualenv`` 1.7 and later]
232+
To start using and see more information: `Virtual Environments <http://github.com/kennethreitz/python-guide/blob/master/docs/dev/virtualenvs.rst>`_ docs.
328233

329234
Other Tools
330235
:::::::::::

‎docs/dev/virtualenvs.rst‎

Lines changed: 57 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
Virtual Environments
22
====================
33

4-
A Virtual Environment, put simply, is an isolated working copy of Python which
5-
allows you to work on a specific project without worry of affecting other
6-
projects.
4+
A Virtual Environment is a tool to keep the dependencies required by different projects
5+
in separate places, by creating virtual Python environments for them. It solves the
6+
"Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
7+
your global site-packages directory clean and manageable.
78

89
For example, you can work on a project which requires Django 1.3 while also
910
maintaining a project which requires Django 1.0.
@@ -12,9 +13,10 @@ virtualenv
1213
----------
1314

1415
`virtualenv <http://pypi.python.org/pypi/virtualenv>`_ is a tool to create
15-
isolated Python environments.
16+
isolated Python environments. virtualenv creates a folder which contains all the
17+
necessary executables to use the packages that a Python project would need.
1618

17-
Install it via pip:
19+
Install virtualenv via pip:
1820

1921
.. code-block:: console
2022
@@ -23,12 +25,18 @@ Install it via pip:
2325
Basic Usage
2426
~~~~~~~~~~~
2527

26-
1. Create a virtual environment:
28+
1. Create a virtual environment for a project:
2729

2830
.. code-block:: console
2931
32+
$ cd my_project_folder
3033
$ virtualenv venv
3134
35+
``virtualenv venv`` will create a folder in the current directory which will contain
36+
the Python executable files, and a copy of the ``pip`` library which you can use to
37+
install other packages. The name of the virtual environment (in this case, it was ``venv``)
38+
can be anything; omitting the name will place the files in the current directory instead.
39+
3240
This creates a copy of Python in whichever directory you ran the command in,
3341
placing it in a folder named :file:`venv`.
3442

@@ -46,8 +54,16 @@ This will use the Python interpreter in :file:`/usr/bin/python2.7`
4654
4755
$ source venv/bin/activate
4856
49-
You can then begin installing any new modules without affecting the system
50-
default Python or other virtual environments.
57+
The name of the current virtual environment will now appear on the left of
58+
the prompt (e.g. ``(venv)Your-Computer:your_project UserName$)`` to let you know
59+
that it's active. From now on, any package that you install using pip will be
60+
placed in the ``venv`` folder, isolated from the global Python installation.
61+
62+
Install packages as usual, for example:
63+
64+
.. code-block:: console
65+
66+
$ pip install requests
5167
5268
3. If you are done working in the virtual environment for the moment, you can
5369
deactivate it:
@@ -59,12 +75,44 @@ default Python or other virtual environments.
5975
This puts you back to the system's default Python interpreter with all its
6076
installed libraries.
6177

62-
To delete a virtual environment, just delete its folder.
78+
To delete a virtual environment, just delete its folder. (In this case,
79+
it would be ``rm -rf venv``.)
6380

6481
After a while, though, you might end up with a lot of virtual environments
6582
littered across your system, and its possible you'll forget their names or
6683
where they were placed.
6784

85+
Other Notes
86+
~~~~~~~~~~~
87+
88+
Running ``virtualenv`` with the option :option:`--no-site-packages` will not
89+
include the packages that are installed globally. This can be useful
90+
for keeping the package list clean in case it needs to be accessed later.
91+
[This is the default behavior for ``virtualenv`` 1.7 and later.]
92+
93+
In order to keep your environment consistent, it's a good idea to "freeze"
94+
the current state of the environment packages. To do this, run
95+
96+
.. code-block:: console
97+
98+
$ pip freeze > requirements.txt
99+
100+
This will create a :file:`requirements.txt` file, which contains a simple
101+
list of all the packages in the current environment, and their respective
102+
versions. Later it will be easier for a different developer (or you, if you
103+
need to re-create the environment) to install the same packages using the
104+
same versions:
105+
106+
.. code-block:: console
107+
108+
$ pip install -r requirements.txt
109+
110+
This can help ensure consistency across installations, across deployments,
111+
and across developers.
112+
113+
Lastly, remember to exclude the virtual environment folder from source
114+
control by adding it to the ignore list.
115+
68116
virtualenvwrapper
69117
-----------------
70118

‎docs/starting/install/linux.rst‎

Lines changed: 9 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -45,41 +45,18 @@ To install pip, simply open a command prompt and run
4545
$ easy_install pip
4646
4747
48-
Virtualenv
49-
----------
48+
Virtual Environments
49+
--------------------
5050

51-
After Setuptools & Pip, the next development tool that you should install is
52-
`virtualenv <http://pypi.python.org/pypi/virtualenv/>`_. Use pip
51+
A Virtual Environment is a tool to keep the dependencies required by different projects
52+
in separate places, by creating virtual Python environments for them. It solves the
53+
"Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
54+
your global site-packages directory clean and manageable.
5355

54-
.. code-block:: console
55-
56-
$ pip install virtualenv
57-
58-
The virtualenv kit provides the ability to create virtual Python environments
59-
that do not interfere with either each other, or the main Python installation.
60-
If you install virtualenv before you begin coding then you can get into the
61-
habit of using it to create completely clean Python environments for each
62-
project. This is particularly important for Web development, where each
63-
framework and application will have many dependencies.
64-
65-
To set up a new Python environment, change the working directory to where ever
66-
you want to store the environment, and run the virtualenv utility in your
67-
project's directory
68-
69-
.. code-block:: console
70-
71-
$ virtualenv venv
72-
73-
To use an environment, run ``source venv/bin/activate``. Your command prompt
74-
will change to show the active environment. Once you have finished working in
75-
the current virtual environment, run ``deactivate`` to restore your settings
76-
to normal.
56+
For example, you can work on a project which requires Django 1.3 while also
57+
maintaining a project which requires Django 1.0.
7758

78-
Each new environment automatically includes a copy of ``pip``, so that you can
79-
setup the third-party libraries and tools that you want to use in that
80-
environment. Put your own code within a subdirectory of the environment,
81-
however you wish. When you no longer need a particular environment, simply
82-
copy your code out of it, and then delete the main directory for the environment.
59+
To start using and see more information: `Virtual Environments <http://github.com/kennethreitz/python-guide/blob/master/docs/dev/virtualenvs.rst>`_ docs.
8360

8461

8562
--------------------------------

‎docs/starting/install/osx.rst‎

Lines changed: 9 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -77,44 +77,19 @@ that is recommended over ``easy_install``. It is superior to ``easy_install`` in
7777
and is actively maintained.
7878

7979

80-
Virtualenv
81-
----------
80+
Virtual Environments
81+
--------------------
8282

83-
After Setuptools & Pip, the next development tool that you should install is
84-
`virtualenv <http://pypi.python.org/pypi/virtualenv/>`_. Use pip
83+
A Virtual Environment is a tool to keep the dependencies required by different projects
84+
in separate places, by creating virtual Python environments for them. It solves the
85+
"Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
86+
your global site-packages directory clean and manageable.
8587

86-
.. code-block:: console
87-
88-
$ pip install virtualenv
89-
90-
The virtualenv kit provides the ability to create virtual Python environments
91-
that do not interfere with either each other, or the main Python installation.
92-
If you install virtualenv before you begin coding then you can get into the
93-
habit of using it to create completely clean Python environments for each
94-
project. This is particularly important for Web development, where each
95-
framework and application will have many dependencies.
96-
97-
To set up a new Python environment, move into the directory where you would
98-
like to store the environment, and use the ``virtualenv`` utility to create
99-
the new environment.
100-
101-
.. code-block:: console
102-
103-
$ virtualenv venv
104-
105-
To use an environment, run ``source venv/bin/activate``. Your command prompt
106-
will change to show the active environment. Once you have finished working in
107-
the current virtual environment, run ``deactivate`` to restore your settings
108-
to normal.
88+
For example, you can work on a project which requires Django 1.3 while also
89+
maintaining a project which requires Django 1.0.
10990

110-
Each new environment automatically includes a copy of ``pip``, so that you can
111-
setup the third-party libraries and tools that you want to use in that
112-
environment. Put your own code within a subdirectory of the environment,
113-
however you wish. When you no longer need a particular environment, simply
114-
copy your code out of it, and then delete the main directory for the environment.
91+
To start using and see more information: `Virtual Environments <http://github.com/kennethreitz/python-guide/blob/master/docs/dev/virtualenvs.rst>`_ docs.
11592

116-
A useful set of extensions to virtualenv is available in virtualenvwrapper,
117-
`RTFD <http://virtualenvwrapper.readthedocs.org/en/latest/>`_ to find out more.
11893

11994
--------------------------------
12095

‎docs/starting/install/win.rst‎

Lines changed: 9 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -66,45 +66,18 @@ To install pip, run the Python script available here:
6666
`get-pip.py <https://raw.github.com/pypa/pip/master/contrib/get-pip.py>`_
6767

6868

69-
Virtualenv
70-
----------
69+
Virtual Environments
70+
--------------------
7171

72-
After Setuptools & Pip, the next development tool that you should install is
73-
`virtualenv <http://pypi.python.org/pypi/virtualenv/>`_. Use pip
72+
A Virtual Environment is a tool to keep the dependencies required by different projects
73+
in separate places, by creating virtual Python environments for them. It solves the
74+
"Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
75+
your global site-packages directory clean and manageable.
7476

75-
.. code-block:: console
76-
77-
> pip install virtualenv
78-
79-
The virtualenv kit provides the ability to create virtual Python environments
80-
that do not interfere with either each other, or the main Python installation.
81-
If you install virtualenv before you begin coding then you can get into the
82-
habit of using it to create completely clean Python environments for each
83-
project. This is particularly important for Web development, where each
84-
framework and application will have many dependencies.
85-
86-
87-
To set up a new Python environment, change the working directory to wherever
88-
you want to store the environment, and run the virtualenv utility in your
89-
project's directory
90-
91-
.. code-block:: console
92-
93-
> virtualenv venv
94-
95-
To use an environment, run the :file:`activate.bat` batch file in the :file:`Scripts`
96-
subdirectory of that environment. Your command prompt will change to show the
97-
active environment. Once you have finished working in the current virtual
98-
environment, run the :file:`deactivate.bat` batch file to restore your settings to
99-
normal.
100-
101-
Each new environment automatically includes a copy of ``pip`` in the
102-
:file:`Scripts` subdirectory, so that you can setup the third-party libraries and
103-
tools that you want to use in that environment. Put your own code within a
104-
subdirectory of the environment, however you wish. When you no longer need a
105-
particular environment, simply copy your code out of it, and then delete the
106-
main directory for the environment.
77+
For example, you can work on a project which requires Django 1.3 while also
78+
maintaining a project which requires Django 1.0.
10779

80+
To start using and see more information: `Virtual Environments <http://github.com/kennethreitz/python-guide/blob/master/docs/dev/virtualenvs.rst>`_ docs.
10881

10982

11083
--------------------------------

0 commit comments

Comments
 (0)