22/12/2017 Hacker Codex

Hacker Codex

Python Development
Environment on macOS Sierra
and El Capitan
Last updated: September 28, 2017

While installing Python and Virtualenv on macOS Sierra

can be done several ways, this tutorial will guide you
through the process of configuring a stock Mac system
into a solid Python development environment.

First steps
This guide assumes that you have already installed
Homebrew. For details, please follow the steps in the
macOS Configuration Guide.

Python
We are going to install the latest 2.7.x version of Python
via Homebrew. Why bother, you ask, when Apple includes
Python along with macOS? Here are some reasons:

When using the bundled Python, macOS updates

can nuke your Python packages, forcing you to re-
install them.
As new versions of Python are released, the Python
bundled with macOS will become out-of-date.
Homebrew always has the most recent version.
Apple has made significant changes to its bundled
Python, potentially resulting in hidden bugs.
Homebrew’s Python includes the latest versions of
Pip and Setuptools (Python package
management tools)

Along the same lines, the version of OpenSSL that comes

with macOS is out-of-date, so we’re going to tell

https://hackercodex.com/guide/python-development-environment-on-mac-osx/ 1/8
22/12/2017 Hacker Codex

Homebrew to download the latest OpenSSL and compile

Python with it.

Use the following command to install Python

via Homebrew:

brew install python

You’ve already modified your PATH as mentioned in the

macOS Configuration Guide, right? If not, please do
so now.

Since Python 2.7 is deprecated, I highly recommend that

you also install Python 3:

brew install python3

This makes it easy to test your code on both Python 2.7

and Python 3. More importantly, since Python 3 is the
present and future of all things Python, the examples
below assume you have installed Python 3.

Pip
Let’s say you want to install a Python package, such as the
fantastic Virtualenv environment isolation tool. While
nearly every Python-related article for macOS tells the
reader to install it via sudo pip install virtualenv ,
the downsides of this method include:

1. installs with root permissions

2. installs into the system /Library
3. yields a less reliable environment when using
Homebrew’s Python

As you might have guessed by now, we’re going to use the

tools provided by Homebrew to install the Python
packages that we want to be globally available. When
installing via Homebrew’s Pip, packages will be installed
to /usr/local/lib/python{version}/site-packages ,
with binaries placed in /usr/local/bin .

https://hackercodex.com/guide/python-development-environment-on-mac-osx/ 2/8
22/12/2017 Hacker Codex

In July 2018, Homebrew changed the names of Python-

related binaries to avoid potential confusion with those
bundled with macOS. As a result, pip became pip2 , et
cetera. Between this change and the many new
improvements in Python 3, it seems a good time to start
using pip3 for all the examples that will follow below. If
you don’t want to install Python 3 or would prefer your
global packages to use the older, deprecated Python 2.7,
you can replace the relevant invocations below with
pip2 instead.

Version control (optional)
The first thing I pip-install is Mercurial, since I have
Mercurial repositories that I push to both Bitbucket and
GitHub. If you don’t want to install Mercurial, you can
skip ahead to the next section.

The following command will install Mercurial and hg-git:

pip3 install Mercurial hg-git

At a minimum, you’ll need to add a few lines to your .hgrc

file in order to use Mercurial:

vim ~/.hgrc

The following lines should get you started; just be sure to

change the values to your name and email
address, respectively:

[ui]
username = YOUR NAME <address@example.com>

To test whether Mercurial is configured and ready for use,

run the following command:

hg debuginstall

https://hackercodex.com/guide/python-development-environment-on-mac-osx/ 3/8
22/12/2017 Hacker Codex

If the last line in the response is “no problems detected”,

then Mercurial has been installed and
configured properly.

Virtualenv
Python packages installed via the steps above are global in
the sense that they are available across all of your
projects. That can be convenient at times, but it can also
create problems. For example, sometimes one project
needs the latest version of Django, while another project
needs an older Django version to retain compatibility with
a critical third-party extension. This is one of many use
cases that Virtualenv was designed to solve. On my
systems, only a handful of general-purpose Python
packages (such as Mercurial and Virtualenv are globally
available — every other package is confined to
virtual environments.

With that explanation behind us, let’s install Virtualenv:

pip3 install virtualenv

Create some directories to store our projects, virtual

environments, and Pip configuration file, respectively:

mkdir -p ~/Projects ~/Virtualenvs ~/Library/Appli

cation\ Support/pip

We’ll then open Pip’s configuration file (which may be

created if it doesn’t exist yet)…

vim ~/Library/Application\ Support/pip/pip.conf

… and add some lines to it:

[install]
require-virtualenv = true

[uninstall]
require-virtualenv = true

https://hackercodex.com/guide/python-development-environment-on-mac-osx/ 4/8
22/12/2017 Hacker Codex

Now we have Virtualenv installed and ready to create new

virtual environments, which we will store in
~/Virtualenvs . New virtual environments can be
created via:

cd ~/Virtualenvs
virtualenv foobar

If you have both Python 2.x and 3.x and want to create a
Python 3.x virtualenv:

virtualenv -p python3 foobar-py3

… which makes it easier to switch between Python 2.x and

3.x foobar environments.

Restricting Pip to virtual environments

What happens if we think we are working in an active
virtual environment, but there actually is no virtual
environment active, and we install something via pip3
install foobar ? Well, in that case the foobar package
gets installed into our global site-packages, defeating the
purpose of our virtual environment isolation.

In an effort to avoid mistakenly Pip-installing a project-

specific package into my global site-packages, I previously
used easy_install for global packages and the
virtualenv-bundled Pip for installing packages into virtual
environments. That accomplished the isolation objective,
since Pip was only available from within virtual
environments, making it impossible for me to pip3
install foobar into my global site-packages by mistake.
But easy_install has some deficiencies, such as the
inability to uninstall a package, and I found myself
wanting to use Pip for both global and virtual
environment packages.

Thankfully, Pip has an undocumented setting (source)

that tells it to bail out if there is no active virtual
environment, which is exactly what I want. In fact, we’ve

https://hackercodex.com/guide/python-development-environment-on-mac-osx/ 5/8
22/12/2017 Hacker Codex

already set that above, via the require-virtualenv =

true directive in Pip’s configuration file. For example,
let’s see what happens when we try to install a package in
the absence of an activated virtual environment:

$ pip3 install markdown

Could not find an activated virtualenv (required)
.

Perfect! But once that option is set, how do we install or

upgrade a global package? We can temporarily turn off
this restriction by defining a new function in ~/.bashrc :

gpip(){
PIP_REQUIRE_VIRTUALENV="" pip3 "$@"
}

(As usual, after adding the above you must run source
~/.bash_profile for the change to take effect.)

If in the future we want to upgrade our global packages,

the above function enables us to do so via:

gpip install --upgrade pip setuptools wheel virtu

alenv

You could achieve the same effect via

PIP_REQUIRE_VIRTUALENV="" pip3 install --upgrade
foobar , but that’s much more cumbersome to type.

Creating virtual environments
Let’s create a virtual environment for Pelican, a Python-
based static site generator:

cd ~/Virtualenvs
virtualenv pelican

Change to the new environment and activate it via:

cd pelican
source bin/activate

https://hackercodex.com/guide/python-development-environment-on-mac-osx/ 6/8
22/12/2017 Hacker Codex

To install Pelican into the virtual environment, we’ll use

pip :

pip3 install pelican markdown

For more information about virtual environments, read

the Virtualenv docs.

Dotfiles
These are obviously just the basic steps to getting a
Python development environment configured. Feel free to
also check out my dotfiles (GitHub mirror).

If you found this article to be useful, please follow me on

Twitter. Also, if you are interested in server security
monitoring, be sure to sign up for early access to
Monitorial!

Want to be notified when I publish new technical

tutorials?

https://hackercodex.com/guide/python-development-environment-on-mac-osx/ 7/8
22/12/2017 Hacker Codex

https://hackercodex.com/guide/python-development-environment-on-mac-osx/ 8/8