mirror of
https://github.com/kennethreitz/python-guide.git
synced 2026-06-05 23:00:18 +00:00
Merge pull request #495 from tbarn/master
Combined and centralized virtualenv docs, fixes issue #123
This commit is contained in:
Ian Cordasco
+9
-104
@@ -218,113 +218,18 @@ Interpreter Tools
|
||||
:::::::::::::::::
|
||||
|
||||
|
||||
virtualenv
|
||||
----------
|
||||
Virtual Environments
|
||||
--------------------
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
`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.
|
||||
For example, you can work on a project which requires Django 1.3 while also
|
||||
maintaining a project which requires Django 1.0.
|
||||
|
||||
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
|
||||
|
||||
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]
|
||||
To start using and see more information: `Virtual Environments <http://github.com/kennethreitz/python-guide/blob/master/docs/dev/virtualenvs.rst>`_ docs.
|
||||
|
||||
Other Tools
|
||||
:::::::::::
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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:
|
||||
@@ -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
|
||||
-----------------
|
||||
|
||||
|
||||
@@ -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
|
||||
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 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.
|
||||
To start using and see more information: `Virtual Environments <http://github.com/kennethreitz/python-guide/blob/master/docs/dev/virtualenvs.rst>`_ docs.
|
||||
|
||||
|
||||
--------------------------------
|
||||
|
||||
@@ -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
|
||||
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.
|
||||
|
||||
--------------------------------
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
--------------------------------
|
||||
|
||||
Reference in New Issue
Block a user