Skip to content

Combined and centralized virtualenv docs, fixes issue #123 #495

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sigmavirus24 merged 12 commits into from
Nov 20, 2014
Merged

Combined and centralized virtualenv docs, fixes issue #123 #495

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
8e6bec7
Consolidating info from dev/env.rst on virtualenv
tbarn Oct 25, 2014
cb984f2
Fixed new line so code-block shows
tbarn Oct 25, 2014
53865c5
Added example
tbarn Oct 25, 2014
c5ab9e8
Grammar fix
tbarn Nov 11, 2014
e4025c1
Removed virtualenv and linked to central location
tbarn Nov 11, 2014
86148b3
Removed virtualenv and linked to central location
tbarn Nov 11, 2014
1123507
Removed virtualenv and linked to central location
tbarn Nov 11, 2014
34bfcfc
Removed virtualenv and linked to central location
tbarn Nov 11, 2014
17d0f7f
Title style fix in env.rst
tbarn Nov 20, 2014
8f2a936
Title style fix in linux.rst
tbarn Nov 20, 2014
c494783
Title style fix in osx.rst
tbarn Nov 20, 2014
9c7df81
Title style fix in win.rst
tbarn Nov 20, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 9 additions & 104 deletions docs/dev/env.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,113 +218,18 @@ Interpreter Tools
:::::::::::::::::


virtualenv
----------

Virtualenv 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.

`virtualenv <http://www.virtualenv.org/en/latest/index.html>`_ creates
a folder which contains all the necessary executables to use the
packages that a Python project would need. An example workflow is given
below.

Install virtualenv:

.. code-block:: console

$ pip install virtualenv


Create a virtual environment for a project:

.. code-block:: console

$ cd my_project
$ virtualenv venv

``virtualenv venv`` will create a folder in the current directory
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 (in this case, it was ``venv``) can be anything;
omitting the name will place the files in the current directory instead.

To start using the virtual environment, run:

.. code-block:: console

$ source 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:

.. code-block:: console

$ pip install requests
Virtual Environments
--------------------

To stop using an environment, simply type ``deactivate``. To remove the
environment, just remove the directory it was installed into. (In this
case, it would be ``rm -rf venv``.)

Other Notes
^^^^^^^^^^^

Running ``virtualenv`` with the option :option:`--no-site-packages` will not
include the packages that are installed globally. This can be useful
for keeping the package list clean in case it needs to be accessed later.
[This is the default behavior for ``virtualenv`` 1.7 and later.]

In order to keep your environment consistent, it's a good idea to "freeze"
the current state of the environment packages. To do this, run

.. code-block:: console

$ pip freeze > requirements.txt

This will create a :file:`requirements.txt` file, which contains a simple
list of all the packages in the current environment, and their respective
versions. Later it will be easier for a different developer (or you, if you
need to re-create the environment) to install the same packages using the
same versions:

.. code-block:: console

$ pip install -r requirements.txt

This can help ensure consistency across installations, across deployments,
and across developers.

Lastly, remember to exclude the virtual environment folder from source
control by adding it to the ignore list.

virtualenvwrapper
-----------------

`Virtualenvwrapper <http://pypi.python.org/pypi/virtualenvwrapper>`_ makes
virtualenv a pleasure to use by wrapping the command line API with a nicer CLI.

.. code-block:: console

$ pip install virtualenvwrapper


Put this into your :file:`~/.bash_profile` (Linux/Mac) file:

.. code-block:: console
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.

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

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

Other Tools
:::::::::::
Expand Down
66 changes: 57 additions & 9 deletions docs/dev/virtualenvs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
Virtual Environments
====================

A Virtual Environment, put simply, is an isolated working copy of Python which
allows you to work on a specific project without worry of affecting other
projects.
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.
Expand All @@ -12,9 +13,10 @@ virtualenv
----------

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

Install it via pip:
Install virtualenv via pip:

.. code-block:: console

Expand All @@ -23,12 +25,18 @@ Install it via pip:
Basic Usage
~~~~~~~~~~~

1. Create a virtual environment:
1. Create a virtual environment for a project:

.. code-block:: console

$ cd my_project_folder
$ virtualenv venv

``virtualenv venv`` will create a folder in the current directory 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 (in this case, it was ``venv``)
can be anything; omitting the name will place the files in the current directory instead.

This creates a copy of Python in whichever directory you ran the command in,
placing it in a folder named :file:`venv`.

Expand All @@ -46,8 +54,16 @@ This will use the Python interpreter in :file:`/usr/bin/python2.7`

$ source venv/bin/activate

You can then begin installing any new modules without affecting the system
default Python or other virtual environments.
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

3. If you are done working in the virtual environment for the moment, you can
deactivate it:
Expand All @@ -59,12 +75,44 @@ default Python or other virtual environments.
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.
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.

Other Notes
~~~~~~~~~~~

Running ``virtualenv`` with the option :option:`--no-site-packages` will not
include the packages that are installed globally. This can be useful
for keeping the package list clean in case it needs to be accessed later.
[This is the default behavior for ``virtualenv`` 1.7 and later.]

In order to keep your environment consistent, it's a good idea to "freeze"
the current state of the environment packages. To do this, run

.. code-block:: console

$ pip freeze > requirements.txt

This will create a :file:`requirements.txt` file, which contains a simple
list of all the packages in the current environment, and their respective
versions. Later it will be easier for a different developer (or you, if you
need to re-create the environment) to install the same packages using the
same versions:

.. code-block:: console

$ pip install -r requirements.txt

This can help ensure consistency across installations, across deployments,
and across developers.

Lastly, remember to exclude the virtual environment folder from source
control by adding it to the ignore list.

virtualenvwrapper
-----------------

Expand Down
41 changes: 9 additions & 32 deletions docs/starting/install/linux.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,41 +45,18 @@ To install pip, simply open a command prompt and run
$ easy_install pip


Virtualenv
----------
Virtual Environments
--------------------

After Setuptools & Pip, the next development tool that you should install is
`virtualenv <http://pypi.python.org/pypi/virtualenv/>`_. Use pip
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.

.. code-block:: console

$ pip install virtualenv

The virtualenv kit provides the ability to create virtual Python environments
that do not interfere with either each other, or the main Python installation.
If you install virtualenv before you begin coding then you can get into the
habit of using it to create completely clean Python environments for each
project. This is particularly important for Web development, where each
framework and application will have many dependencies.

To set up a new Python environment, change the working directory to where ever
you want to store the environment, and run the virtualenv utility in your
project's directory

.. code-block:: console

$ virtualenv venv

To use an environment, run ``source venv/bin/activate``. Your command prompt
will change to show the active environment. Once you have finished working in
the current virtual environment, run ``deactivate`` to restore your settings
to normal.
For example, you can work on a project which requires Django 1.3 while also
maintaining a project which requires Django 1.0.

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


--------------------------------
Expand Down
43 changes: 9 additions & 34 deletions docs/starting/install/osx.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,44 +77,19 @@ that is recommended over ``easy_install``. It is superior to ``easy_install`` in
and is actively maintained.


Virtualenv
----------
Virtual Environments
--------------------

After Setuptools & Pip, the next development tool that you should install is
`virtualenv <http://pypi.python.org/pypi/virtualenv/>`_. Use pip
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.

.. code-block:: console

$ pip install virtualenv

The virtualenv kit provides the ability to create virtual Python environments
that do not interfere with either each other, or the main Python installation.
If you install virtualenv before you begin coding then you can get into the
habit of using it to create completely clean Python environments for each
project. This is particularly important for Web development, where each
framework and application will have many dependencies.

To set up a new Python environment, move into the directory where you would
like to store the environment, and use the ``virtualenv`` utility to create
the new environment.

.. code-block:: console

$ virtualenv venv

To use an environment, run ``source venv/bin/activate``. Your command prompt
will change to show the active environment. Once you have finished working in
the current virtual environment, run ``deactivate`` to restore your settings
to normal.
For example, you can work on a project which requires Django 1.3 while also
maintaining a project which requires Django 1.0.

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

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

--------------------------------

Expand Down
45 changes: 9 additions & 36 deletions docs/starting/install/win.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,45 +66,18 @@ To install pip, run the Python script available here:
`get-pip.py <https://raw.github.com/pypa/pip/master/contrib/get-pip.py>`_


Virtualenv
----------
Virtual Environments
--------------------

After Setuptools & Pip, the next development tool that you should install is
`virtualenv <http://pypi.python.org/pypi/virtualenv/>`_. Use pip
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.

.. code-block:: console

> pip install virtualenv

The virtualenv kit provides the ability to create virtual Python environments
that do not interfere with either each other, or the main Python installation.
If you install virtualenv before you begin coding then you can get into the
habit of using it to create completely clean Python environments for each
project. This is particularly important for Web development, where each
framework and application will have many dependencies.


To set up a new Python environment, change the working directory to wherever
you want to store the environment, and run the virtualenv utility in your
project's directory

.. code-block:: console

> virtualenv venv

To use an environment, run the :file:`activate.bat` batch file in the :file:`Scripts`
subdirectory of that environment. Your command prompt will change to show the
active environment. Once you have finished working in the current virtual
environment, run the :file:`deactivate.bat` batch file to restore your settings to
normal.

Each new environment automatically includes a copy of ``pip`` in the
:file:`Scripts` subdirectory, so that you can setup the third-party libraries and
tools that you want to use in that environment. Put your own code within a
subdirectory of the environment, however you wish. When you no longer need a
particular environment, simply copy your code out of it, and then delete the
main directory for the environment.
For example, you can work on a project which requires Django 1.3 while also
maintaining a project which requires Django 1.0.

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


--------------------------------
Expand Down