kennethreitz/python-guide
1
0
Fork 0
mirror of https://github.com/kennethreitz/python-guide.git synced 2026-06-05 23:00:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #495 from tbarn/master

Browse Source 
Combined and centralized virtualenv docs, fixes issue #123
This commit is contained in:
Ian Cordasco
2014-11-20 11:31:58 -06:00
parent 3acec129ae 9c7df812c4
commit ef6df059c7
5 changed files with 93 additions and 215 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/dev/env.rst
+9 -104
View File
@@ -218,113 +218,18 @@ Interpreter Tools
::::::::::::::::: :::::::::::::::::
virtualenv Virtual Environments
---------- --------------------
Virtualenv is a tool to keep the dependencies required by different 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. in separate places, by creating virtual Python environments for them. It solves the
It solves the "Project X depends on version 1.x but, Project Y needs 4.x" "Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps
dilemma, and keeps your global site-packages directory clean and manageable. your global site-packages directory clean and manageable.
`virtualenv <http://www.virtualenv.org/en/latest/index.html>`_ creates For example, you can work on a project which requires Django 1.3 while also
a folder which contains all the necessary executables to use the maintaining a project which requires Django 1.0.
packages that a Python project would need. An example workflow is given
below.
Install virtualenv: To start using and see more information: `Virtual Environments <http://github.com/kennethreitz/python-guide/blob/master/docs/dev/virtualenvs.rst>`_ docs.
.. 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
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
$ export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
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]
Other Tools Other Tools
::::::::::: :::::::::::
docs/dev/virtualenvs.rst
+57 -9
View File
@@ -1,9 +1,10 @@
Virtual Environments Virtual Environments
==================== ====================
A Virtual Environment, put simply, is an isolated working copy of Python which A Virtual Environment is a tool to keep the dependencies required by different projects
allows you to work on a specific project without worry of affecting other in separate places, by creating virtual Python environments for them. It solves the
projects. "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 For example, you can work on a project which requires Django 1.3 while also
maintaining a project which requires Django 1.0. maintaining a project which requires Django 1.0.
@@ -12,9 +13,10 @@ virtualenv
---------- ----------
`virtualenv <http://pypi.python.org/pypi/virtualenv>`_ is a tool to create `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 .. code-block:: console
@@ -23,12 +25,18 @@ Install it via pip:
Basic Usage Basic Usage
~~~~~~~~~~~ ~~~~~~~~~~~
1. Create a virtual environment: 1. Create a virtual environment for a project:
.. code-block:: console .. code-block:: console
$ cd my_project_folder
$ virtualenv venv $ 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, This creates a copy of Python in whichever directory you ran the command in,
placing it in a folder named :file:`venv`. placing it in a folder named :file:`venv`.
@@ -46,8 +54,16 @@ This will use the Python interpreter in :file:`/usr/bin/python2.7`
$ source venv/bin/activate $ source venv/bin/activate
You can then begin installing any new modules without affecting the system The name of the current virtual environment will now appear on the left of
default Python or other virtual environments. 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 3. If you are done working in the virtual environment for the moment, you can
deactivate it: deactivate it:
@@ -59,12 +75,44 @@ default Python or other virtual environments.
This puts you back to the system's default Python interpreter with all its This puts you back to the system's default Python interpreter with all its
installed libraries. 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 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 littered across your system, and its possible you'll forget their names or
where they were placed. 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 virtualenvwrapper
----------------- -----------------
docs/starting/install/linux.rst
+9 -32
View File
@@ -45,41 +45,18 @@ To install pip, simply open a command prompt and run
$ easy_install pip $ easy_install pip
Virtualenv Virtual Environments
---------- --------------------
After Setuptools & Pip, the next development tool that you should install is A Virtual Environment is a tool to keep the dependencies required by different projects
`virtualenv <http://pypi.python.org/pypi/virtualenv/>`_. Use pip 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 For example, you can work on a project which requires Django 1.3 while also
maintaining a project which requires Django 1.0.
$ pip install virtualenv To start using and see more information: `Virtual Environments <http://github.com/kennethreitz/python-guide/blob/master/docs/dev/virtualenvs.rst>`_ docs.
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.
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.
-------------------------------- --------------------------------
docs/starting/install/osx.rst
+9 -34
View File
@@ -77,44 +77,19 @@ that is recommended over ``easy_install``. It is superior to ``easy_install`` in
and is actively maintained. and is actively maintained.
Virtualenv Virtual Environments
---------- --------------------
After Setuptools & Pip, the next development tool that you should install is A Virtual Environment is a tool to keep the dependencies required by different projects
`virtualenv <http://pypi.python.org/pypi/virtualenv/>`_. Use pip 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 For example, you can work on a project which requires Django 1.3 while also
maintaining a project which requires Django 1.0.
$ pip install virtualenv To start using and see more information: `Virtual Environments <http://github.com/kennethreitz/python-guide/blob/master/docs/dev/virtualenvs.rst>`_ docs.
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.
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.
A useful set of extensions to virtualenv is available in virtualenvwrapper,
`RTFD <http://virtualenvwrapper.readthedocs.org/en/latest/>`_ to find out more.
-------------------------------- --------------------------------
docs/starting/install/win.rst
+9 -36
View File
@@ -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>`_ `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 A Virtual Environment is a tool to keep the dependencies required by different projects
`virtualenv <http://pypi.python.org/pypi/virtualenv/>`_. Use pip 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 For example, you can work on a project which requires Django 1.3 while also
maintaining a project which requires Django 1.0.
> 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.
To start using and see more information: `Virtual Environments <http://github.com/kennethreitz/python-guide/blob/master/docs/dev/virtualenvs.rst>`_ docs.
-------------------------------- --------------------------------