kennethreitz · Dec 7, 2016 · Mar 14, 2016 · Mar 14, 2016 · Mar 14, 2016 · Mar 15, 2016
diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst
@@ -15,8 +15,8 @@ virtualenv
 ----------
 
 `virtualenv <http://pypi.python.org/pypi/virtualenv>`_ is a tool to create
-isolated Python environments. virtualenv creates a folder which contains all the 
-necessary executables to use the packages that a Python project would need. 
+isolated Python environments. virtualenv creates a folder which contains all the
+necessary executables to use the packages that a Python project would need.
 
 Install virtualenv via pip:
 
@@ -43,23 +43,28 @@ 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`.
 
-You can also use a Python interpreter of your choice.
+You can also use the Python interpreter of your choice (like
+:file:`/usr/bin/python2.7`).
 
 .. code-block:: console
 
    $ virtualenv -p /usr/bin/python2.7 venv
 
-This will use the Python interpreter in :file:`/usr/bin/python2.7`
+or change the interpreter globally with an env variable in ``~/.bashrc``:
+
+.. code-block:: console
+
+   $ export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7
 
 2. To begin using the virtual environment, it needs to be activated:
 
 .. 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 
+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:
@@ -78,7 +83,7 @@ Install packages as usual, for example:
 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. (In this case, 
+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
@@ -102,8 +107,8 @@ the current state of the environment packages. To do this, run
 
 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. You can see the list of installed packages without the requirements 
-format using "pip list". Later it will be easier for a different developer 
+versions. You can see the list of installed packages without the requirements
+format using "pip list". 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:
 
@@ -143,7 +148,7 @@ To install (make sure **virtualenv** is already installed):
 .. code-block:: console
 
   $ pip install virtualenvwrapper-win
-  
+
 In Windows, the default path for WORKON_HOME is %USERPROFILE%\Envs
 
 Basic Usage

diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst
@@ -3,13 +3,16 @@
 Installing Python on Mac OS X
 =============================
 
+.. note::
+    Check out our :ref:`guide for installing Python 3 on OS X<install3-osx>`.
+
 The latest version of Mac OS X, El Capitan, **comes with Python 2.7 out of the box**.
 
-You do not need to install or configure anything else to use Python. Having
-said that, I would strongly recommend that you install the tools and libraries
-described in the next section before you start building Python applications
-for real-world use. In particular, you should always install Setuptools, as it
-makes it much easier for you to use other third-party Python libraries.
+You do not need to install or configure anything else to use Python. Having said
+that, I would strongly recommend that you install the tools and libraries
+described in the next section before you start building Python applications for
+real-world use. In particular, you should always install Setuptools, as it makes
+it much easier for you to install and manage other third-party Python libraries.
 
 The version of Python that ships with OS X is great for learning but it's not
 good for development. The version shipped with OS X may be out of date from the
@@ -30,9 +33,14 @@ minimal but unofficial
 package.
 
 .. note::
-    If you already have Xcode installed or plan to use Homebrew, do not install
-    OSX-GCC-Installer. In combination, the software can cause issues that are
-    difficult to diagnose.
+    If you already have XCode installed, do not install OSX-GCC-Installer.
+    In combination, the software can cause issues that are difficult to
+    diagnose.
+
+.. note::
+    If you perform a fresh install of XCode, you will also need to add the
+    commandline tools by running ``xcode-select --install`` on the terminal.
+
 
 While OS X comes with a large number of UNIX utilities, those familiar with
 Linux systems will notice one key component missing: a decent package manager.
@@ -70,7 +78,7 @@ or Python 3:
 This will take a minute or two. 
 
 
-Setuptools & Pip
+Setuptools and Pip
 ----------------
 
 Homebrew installs Setuptools and ``pip`` for you.
@@ -81,23 +89,23 @@ software over a network (usually the Internet) with a single command
 capability to your own Python software with very little work.
 
 ``pip`` is a tool for easily installing and managing Python packages,
-that is recommended over ``easy_install``. It is superior to ``easy_install`` in `several ways <https://python-packaging-user-guide.readthedocs.io/pip_easy_install/#pip-vs-easy-install>`_,
+that is recommended over ``easy_install``. It is superior to ``easy_install``
+in `several ways <https://python-packaging-user-guide.readthedocs.io/pip_easy_install/#pip-vs-easy-install>`_,
 and is actively maintained.
 
 
 Virtual Environments
 --------------------
 
-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 
+A Virtual Environment (commonly referred to as a '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.
 
 For example, you can work on a project which requires Django 1.10 while also
 maintaining a project which requires Django 1.8.
 
-To start using this and see more information: :ref:`Virtual Environments <virtualenvironments-ref>` docs. 
-
+To start using this and see more information: :ref:`Virtual Environments <virtualenvironments-ref>` docs.
 
 --------------------------------
 

diff --git a/docs/starting/install3/osx.rst b/docs/starting/install3/osx.rst
@@ -0,0 +1,116 @@
+.. _install3-osx:
+
+Installing Python 3 on Mac OS X
+================================
+
+The latest version of Mac OS X, El Capitan, **comes with Python 2.7 out of the box**.
+
+You do not need to install or configure anything else to use Python 2. These
+instructions document the installation of Python 3.
+
+The version of Python that ships with OS X is great for learning but it's not
+good for development. The version shipped with OS X may be out of date from the
+`official current Python release <https://www.python.org/downloads/mac-osx/>`_,
+which is considered the stable production version.
+
+Doing it Right
+--------------
+
+Let's install a real version of Python.
+
+Before installing Python, you'll need to install GCC. GCC can be obtained
+by downloading `XCode <http://developer.apple.com/xcode/>`_, the smaller
+`Command Line Tools <https://developer.apple.com/downloads/>`_ (must have an
+Apple account) or the even smaller `OSX-GCC-Installer <https://github.com/kennethreitz/osx-gcc-installer#readme>`_
+package.
+
+.. note::
+    If you already have XCode installed, do not install OSX-GCC-Installer.
+    In combination, the software can cause issues that are difficult to
+    diagnose.
+
+.. note::
+    If you perform a fresh install of XCode, you will also need to add the
+    commandline tools by running ``xcode-select --install`` on the terminal.
+
+While OS X comes with a large number of UNIX utilities, those familiar with
+Linux systems will notice one key component missing: a package manager.
+`Homebrew <http://brew.sh>`_ fills this void.
+
+To `install Homebrew <http://brew.sh/#install>`_, open :file:`Terminal` or
+your favorite OSX terminal emulator and run
+
+.. code-block:: console
+
+    $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+
+The script will explain what changes it will make and prompt you before the
+installation begins.
+Once you've installed Homebrew, insert the Homebrew directory at the top
+of your :envvar:`PATH` environment variable. You can do this by adding the following
+line at the bottom of your :file:`~/.profile` file
+
+.. code-block:: console
+
+    export PATH=/usr/local/bin:/usr/local/sbin:$PATH
+
+Now, we can install Python 3:
+
+.. code-block:: console
+
+    $ brew install python3
+
+This will take a minute or two.
+
+
+Pip
+----------------
+
+Homebrew installs ``pip3`` for you.
+
+``pip3`` is the alias for the Python 3 version of ``pip`` on systems with both
+the Homebrew'd Python 2 and 3 installed.
+
+Working with Python3
+--------------------
+
+At this point, you have the system Python 2.7 available, potentially the
+:ref:`Homebrew version of Python 2 <install-osx>` installed, and the Homebrew
+version of Python 3 as well.
+
+.. code-block:: console
+
+    $ python
+
+will launch the Python 2 interpreter.
+
+.. code-block:: console
+
+    $ python3
+
+will launch the Python 3 interpreter
+
+``pip3`` and ``pip`` will both be available.  If the Homebrew version of Python
+2 is not installed, they will be the same.  If the Homebrew version of Python 2
+is installed then ``pip`` will point to Python 2 and ``pip3`` will point to
+Python 3.
+
+
+Virtual Environments
+--------------------
+
+A Virtual Environment (commonly referred to as a '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.
+
+For example, you can work on a project which requires Django 1.10 while also
+maintaining a project which requires Django 1.8.
+
+To start using this and see more information: :ref:`Virtual Environments <virtualenvironments-ref>` docs.
+
+--------------------------------
+
+This page is a remixed version of `another guide <http://www.stuartellis.eu/articles/python-development-windows/>`_,
+which is available under the same license.
diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst
@@ -13,9 +13,10 @@ other third-party Python libraries.
 Installation Guides
 -------------------
 
-These guides go over the proper installation of :ref:`Python 2.7 <which-python>`
-for development purposes, as well as setuptools, pip, and virtualenv setup.
+These guides go over the proper installation of :ref:`Python <which-python>`
+for development purposes, as well as setuptools, pip and virtualenv.
 
-- :ref:`Mac OS X <install-osx>`.
-- :ref:`Microsoft Windows <install-windows>`.
-- :ref:`Linux <install-linux>`.
+- :ref:`Python 3 on MacOS <install3-osx>`.
+- :ref:`Python 2 on MacOS <install-osx>`.
+- :ref:`Python 2 on Microsoft Windows <install-windows>`.
+- :ref:`Python 2 on Ubuntu Linux <install-linux>`.