How to Install Pyramid on Mac OS X

This guide will walk you through the steps of installing Pyramid on Mac OS X from the very beginning. This guide is targeted toward the complete newbie to Pyramid and Python, and aims to simplify an often confusing process fraught with frustrating pitfalls.


  • A Macintosh computer running Mac OS X (10.5.x or greater recommended).

  • Xcode (recommended).

    At some point, you may need Xcode tools to “make” or compile applications from source code. Experienced developers on the Mac know this, and by installing Xcode once, they “set it and forget it”.

    • For 10.5.x, use Xcode 3.1.4.

    • For 10.6.x, use Xcode 3.2.x or later.

      Visit the Apple Developer Connection website to download a massive installer, or use the Mac OS X installation DVD that came with your computer.

      Optionally, 10.6.x and later can run Xcode 4.x. However Apple charges a nominal fee to download Xcode 4 which is $4.99 at the time of this writing. Visit the Apple Developer Tools website for more information.

  • Python 2.7.x or greater, but less than Python 3.x.

    Python comes pre-installed on Mac OS X, but due to Apple’s release cycle, it’s often one or even two years old. The overwhelming recommendation of the “MacPython” community is to upgrade your Python by downloading and installing a newer version from the Python standard release page. [1]. Note that using the pre-installed (aka “system” Python) is almost never a good idea on Mac OS X, even if the Python version happens to be fairly recent, due to heavy customizations made to the Python environment by Apple themselves. Do yourself a favor and download and install a custom Python instead.

    Python Releases

    At the time of this writing, Pyramid does not yet run under Python 3.x.

Configure Your Python Development Environment for Pyramid

Next we need to configure a Python environment for developing Pyramid applications by installing a few tools.

Install for setuptools

Python projects often rely on third party modules to obtain added functionality. These modules are packaged using distutils, and they contain a Python script named By executing this script, the developer can quickly and easily install the modules from source. Often it is as easy as navigating to the directory containing the script, and executing the following command:

python install

and the module will install itself.

However, not all scripts are well-written and they may blindly attempt to import the setuptools bootstrap module even though is usually not installed on the user’s machine. This causes much trouble. [2]

To remedy the situation, we need to install the missing module on our system. Execute the following commands in Terminal:

cd ~
curl -O
sudo python

Install virtualenv Using virtualenv-burrito

virtualenv is a tool that creates clean sandboxes for development. This removes the potential for conflicts from existing system libraries and allows you to isolate dependencies. [3]

virtualenvwrapper is a tool that makes working with virtualenv easier [4], and virtualenv-burrito is a single-command tool that installs and sets up virtualenvwrapper for you. [5]

Execute the following commands in Terminal:

cd ~
curl -s | bash

If successful, you will see this:


Done with setup!

The virtualenvwrapper environment will be available when you login.

To start it now, run this:
source /Users/<username>/.venvburrito/

Next run this command, substituting your username for <username>:

source /Users/<username>/.venvburrito/

And you will see this:

To create a virtualenv, run:
mkvirtualenv <cool-name>

That statement is a little incomplete. Read on for an explanation.

Create a New virtualenv for Pyramid

When making a new virtualenv, we do not want to include any dependencies from outside the virtualenv, so we want to use the –no-site-packages flag. Run the command:

mkvirtualenv --no-site-packages pyramid

Now activate the new virtualenv:

workon pyramid

Now cd to the virtualenv directory:

cd ~/.virtualenvs/pyramid

And now the moment you’ve been waiting for…

Install Pyramid

Run the command:

bin/easy_install pyramid

Pyramid should now be installed.

What Next?

Try the Pyramid Quick Tutorial.

Read Pyramid Documentation.

Contribute to the Pylons Project Documentation

The Pylons Project documentation uses Sphinx. [6] It is recommended to install Sphinx into the current virtualenv using easy_install:

easy_install -U Sphinx

Visit the Sphinx website.

The Pylons Project documentation has several components.


[1]Python on the Mac
[2]ez_setup (Sridhar Ratnakumar)
[3]virtualenv (Ian Bicking)
[4]virtualenvwrapper (Doug Hellmann)
[5]virtualenv-burrito (Jeremy Avnet)