diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst
index 11f924882..344f56971 100644
--- a/docs/dev/virtualenvs.rst
+++ b/docs/dev/virtualenvs.rst
@@ -1,7 +1,8 @@
.. _virtualenvironments-ref:
+#############################
Pipenv & Virtual Environments
-=============================
+#############################
.. image:: /_static/photos/35294660055_42c02b2316_k_d.jpg
@@ -15,12 +16,13 @@ presented here is most directly applicable to the development and deployment of
network services (including web applications), but is also very well suited to
managing development and testing environments for any kind of project.
-.. Note:: This guide is written for Python 3, however, these instructions
+.. note:: This guide is written for Python 3, however, these instructions
should work fine on Python 2.7—if you are still using it, for some reason.
+*********************************
Make sure you've got Python & pip
----------------------------------
+*********************************
Before you go any further, make sure you have Python and that it's available
from your command line. You can check this by simply running:
@@ -33,13 +35,14 @@ You should get some output like ``3.6.2``. If you do not have Python, please
install the latest 3.x version from `python.org`_ or refer to the
`Installing Python`_ section of this guide.
-.. Note:: If you're newcomer and you get an error like this:
+.. note::
+ If you're newcomer and you get an error like this:
.. code-block:: python
>>> python
Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
+ File "<stdin>", line 1, in <module>
NameError: name 'python' is not defined
It's because this command is intended to be run in a *shell* (also called
@@ -65,8 +68,9 @@ using your OS package manager, you may have to `install pip <https://pip.pypa.io
.. _Installing Python: https://docs.python-guide.org/starting/installation/
+*****************
Installing Pipenv
------------------
+*****************
`Pipenv`_ is a dependency manager for Python projects. If you're familiar
with Node.js' `npm`_ or Ruby's `bundler`_, it is similar in spirit to those
@@ -81,7 +85,8 @@ Use ``pip`` to install Pipenv:
$ pip install --user pipenv
-.. Note:: This does a `user installation`_ to prevent breaking any system-wide
+.. note::
+ This does a `user installation`_ to prevent breaking any system-wide
packages. If ``pipenv`` isn't available in your shell after installation,
you'll need to add the `user base`_'s binary directory to your ``PATH``.
@@ -110,7 +115,7 @@ Use ``pip`` to install Pipenv:
.. _Control Panel: https://msdn.microsoft.com/en-us/library/windows/desktop/bb776899(v=vs.85).aspx
Installing packages for your project
-------------------------------------
+====================================
Pipenv manages dependencies on a per-project basis. To install packages,
change into your project's directory (or just an empty directory for this
@@ -141,15 +146,15 @@ when you share your project with others. You should get output similar to this
Virtualenv location: ~/.local/share/virtualenvs/tmp-agwWamBd
Installing requests...
Collecting requests
- Using cached requests-2.18.4-py2.py3-none-any.whl
+ Using cached requests-2.18.4-py2.py3-none-any.whl
Collecting idna<2.7,>=2.5 (from requests)
- Using cached idna-2.6-py2.py3-none-any.whl
+ Using cached idna-2.6-py2.py3-none-any.whl
Collecting urllib3<1.23,>=1.21.1 (from requests)
- Using cached urllib3-1.22-py2.py3-none-any.whl
+ Using cached urllib3-1.22-py2.py3-none-any.whl
Collecting chardet<3.1.0,>=3.0.2 (from requests)
- Using cached chardet-3.0.4-py2.py3-none-any.whl
+ Using cached chardet-3.0.4-py2.py3-none-any.whl
Collecting certifi>=2017.4.17 (from requests)
- Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
+ Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
Installing collected packages: idna, urllib3, chardet, certifi, requests
Successfully installed certifi-2017.7.27.1 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22
@@ -158,9 +163,8 @@ when you share your project with others. You should get output similar to this
.. _Requests: https://python-requests.org
-
Using installed packages
-------------------------
+========================
Now that Requests is installed you can create a simple ``main.py`` file to
use it:
@@ -189,16 +193,15 @@ Using ``$ pipenv run`` ensures that your installed packages are available to
your script. It's also possible to spawn a new shell that ensures all commands
have access to your installed packages with ``$ pipenv shell``.
-
Next steps
-----------
+==========
Congratulations, you now know how to install and use Python packages! ✨ 🍰 ✨
-
+***********************
Lower level: virtualenv
-=======================
+***********************
`virtualenv <http://pypi.python.org/pypi/virtualenv>`_ is a tool to create
isolated Python environments. virtualenv creates a folder which contains all the
@@ -210,23 +213,23 @@ Install virtualenv via pip:
.. code-block:: console
- $ pip install virtualenv
+ $ pip install virtualenv
Test your installation
.. code-block:: console
- $ virtualenv --version
+ $ virtualenv --version
Basic Usage
-~~~~~~~~~~~
+===========
1. Create a virtual environment for a project:
.. code-block:: console
- $ cd my_project_folder
- $ virtualenv my_project
+ $ cd my_project_folder
+ $ virtualenv my_project
``virtualenv my_project`` will create a folder in the current directory which will
contain the Python executable files, and a copy of the ``pip`` library which you
@@ -242,19 +245,19 @@ You can also use the Python interpreter of your choice (like
.. code-block:: console
- $ virtualenv -p /usr/bin/python2.7 my_project
+ $ virtualenv -p /usr/bin/python2.7 my_project
or change the interpreter globally with an env variable in ``~/.bashrc``:
.. code-block:: console
- $ export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7
+ $ export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7
2. To begin using the virtual environment, it needs to be activated:
.. code-block:: console
- $ source my_project/bin/activate
+ $ source my_project/bin/activate
The name of the current virtual environment will now appear on the left of
the prompt (e.g. ``(my_project)Your-Computer:your_project UserName$)`` to let you know
@@ -272,7 +275,7 @@ Install packages as usual, for example:
.. code-block:: console
- $ deactivate
+ $ deactivate
This puts you back to the system's default Python interpreter with all its
installed libraries.
@@ -285,7 +288,7 @@ littered across your system, and its possible you'll forget their names or
where they were placed.
Other Notes
-~~~~~~~~~~~
+===========
Running ``virtualenv`` with the option ``--no-site-packages`` will not
include the packages that are installed globally. This can be useful
@@ -318,8 +321,10 @@ control by adding it to the ignore list (see :ref:`Version Control Ignores<versi
.. _virtualenvwrapper-ref:
+
+*****************
virtualenvwrapper
------------------
+*****************
`virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/en/latest/index.html>`_
provides a set of commands which makes working with virtual environments much
@@ -329,9 +334,9 @@ To install (make sure **virtualenv** is already installed):
.. code-block:: console
- $ pip install virtualenvwrapper
- $ export WORKON_HOME=~/Envs
- $ source /usr/local/bin/virtualenvwrapper.sh
+ $ pip install virtualenvwrapper
+ $ export WORKON_HOME=~/Envs
+ $ source /usr/local/bin/virtualenvwrapper.sh
(`Full virtualenvwrapper install instructions <https://virtualenvwrapper.readthedocs.io/en/latest/install.html>`_.)
@@ -341,18 +346,18 @@ To install (make sure **virtualenv** is already installed):
.. code-block:: console
- $ pip install virtualenvwrapper-win
+ $ pip install virtualenvwrapper-win
In Windows, the default path for WORKON_HOME is %USERPROFILE%\Envs
Basic Usage
-~~~~~~~~~~~
+===========
1. Create a virtual environment:
.. code-block:: console
- $ mkvirtualenv my_project
+ $ mkvirtualenv my_project
This creates the :file:`my_project` folder inside :file:`~/Envs`.
@@ -360,7 +365,7 @@ This creates the :file:`my_project` folder inside :file:`~/Envs`.
.. code-block:: console
- $ workon my_project
+ $ workon my_project
Alternatively, you can make a project, which creates the virtual environment,
and also a project directory inside ``$WORKON_HOME``, which is ``cd`` -ed into
@@ -368,7 +373,7 @@ when you ``workon myproject``.
.. code-block:: console
- $ mkproject myproject
+ $ mkproject myproject
**virtualenvwrapper** provides tab-completion on environment names. It really
helps when you have a lot of environments and have trouble remembering their
@@ -381,16 +386,16 @@ can quickly switch between environments.
.. code-block:: console
- $ deactivate
+ $ deactivate
4. To delete:
.. code-block:: console
- $ rmvirtualenv venv
+ $ rmvirtualenv venv
Other useful commands
-~~~~~~~~~~~~~~~~~~~~~
+=====================
``lsvirtualenv``
List all of the environments.
@@ -407,14 +412,19 @@ Other useful commands
`Full list of virtualenvwrapper commands <https://virtualenvwrapper.readthedocs.io/en/latest/command_ref.html>`_.
+
+******************
virtualenv-burrito
-------------------
+******************
With `virtualenv-burrito <https://github.com/brainsik/virtualenv-burrito>`_, you
can have a working virtualenv + virtualenvwrapper environment in a single command.
+
+*******
autoenv
--------
+*******
+
When you ``cd`` into a directory containing a :file:`.env`, `autoenv <https://github.com/kennethreitz/autoenv>`_
automagically activates the environment.
@@ -422,11 +432,11 @@ Install it on Mac OS X using ``brew``:
.. code-block:: console
- $ brew install autoenv
+ $ brew install autoenv
And on Linux:
.. code-block:: console
- $ git clone git://github.com/kennethreitz/autoenv.git ~/.autoenv
- $ echo 'source ~/.autoenv/activate.sh' >> ~/.bashrc
+ $ git clone git://github.com/kennethreitz/autoenv.git ~/.autoenv
+ $ echo 'source ~/.autoenv/activate.sh' >> ~/.bashrc