Installation

PyPy

PyPy is the fastest way to run your Falcon app. However, note that only the PyPy 2.7 compatible release is currently supported.

$ pip install falcon

CPython

Falcon also fully supports CPython 2.6-2.7, and 3.3+.

A universal wheel is available on PyPI for the the Falcon framework. Installing it is as simple as:

$ pip install falcon

If ujson is available, Falcon will use it to speed up error response serialization and query string parsing. Note that ujson can actually be slower on PyPy than the standard json module due to ctypes overhead, and so we recommend only using ujson with CPython deployments:

$ pip install ujson

Installing the Falcon wheel is a great way to get up and running quickly in a development environment, but for an extra speed boost when deploying your application in production, Falcon can compile itself with Cython.

The following commands tell pip to install Cython, and then to invoke Falcon’s setup.py, which will in turn detect the presence of Cython and then compile (AKA cythonize) the Falcon framework with the system’s default C compiler.

$ pip install cython
$ pip install --no-binary :all: falcon

If you want to verify that Cython is being invoked, simply pass -v to pip in order to echo the compilation commands:

$ pip install -v --no-binary :all: falcon

Installing on OS X

Xcode Command Line Tools are required to compile Cython. Install them with this command:

$ xcode-select --install

The Clang compiler treats unrecognized command-line options as errors; this can cause problems under Python 2.6, for example:

clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]

You might also see warnings about unused functions. You can work around these issues by setting additional Clang C compiler flags as follows:

$ export CFLAGS="-Qunused-arguments -Wno-unused-function"

Dependencies

Falcon depends on six and python-mimeparse. python-mimeparse is a better-maintained fork of the similarly named mimeparse project. Normally the correct package will be selected by Falcon’s setup.py. However, if you are using an alternate strategy to manage dependencies, please take care to install the correct package in order to avoid errors.

WSGI Server

Falcon speaks WSGI, and so in order to serve a Falcon app, you will need a WSGI server. Gunicorn and uWSGI are some of the more popular ones out there, but anything that can load a WSGI app will do.

All Windows developers can use Waitress production-quality pure-Python WSGI server with very acceptable performance. Unfortunately Gunicorn is still not working on Windows and uWSGI need to have Cygwin on Windows installed. Waitress can be good alternative for Windows users if they want quick start using Falcon on it.

$ pip install [gunicorn|uwsgi|waitress]

Source Code

Falcon lives on GitHub, making the code easy to browse, download, fork, etc. Pull requests are always welcome! Also, please remember to star the project if it makes you happy. :)

Once you have cloned the repo or downloaded a tarball from GitHub, you can install Falcon like this:

$ cd falcon
$ pip install .

Or, if you want to edit the code, first fork the main repo, clone the fork to your desktop, and then run the following to install it using symbolic linking, so that when you change your code, the changes will be automagically available to your app without having to reinstall the package:

$ cd falcon
$ pip install -e .

You can manually test changes to the Falcon framework by switching to the directory of the cloned repo and then running pytest:

$ cd falcon
$ pip install -r requirements/tests
$ pytest tests

Or, to run the default set of tests:

$ pip install tox && tox

Finally, to build Falcon’s docs from source, simply run:

$ pip install tox && tox -e docs

Once the docs have been built, you can view them by opening the following index page in your browser. On OS X it’s as simple as:

$ open docs/_build/html/index.html

Or on Linux:

$ xdg-open docs/_build/html/index.html