Installation#

PyPy#

PyPy is the fastest way to run your Falcon app. PyPy3.8+ is supported as of PyPy v7.3.7.

$ pip install falcon

Or, to install the latest beta or release candidate, if any:

$ pip install --pre falcon

CPython#

Falcon fully supports CPython 3.8+.

The latest stable version of Falcon can be installed directly from PyPI:

$ pip install falcon

Or, to install the latest beta or release candidate, if any:

$ pip install --pre falcon

In order to provide an extra speed boost, Falcon automatically compiles itself with Cython. Wheels containing pre-compiled binaries are available from PyPI for the majority of common platforms (see Binary Wheels below for the complete list of the platforms that we target, or simply check Falcon files on PyPI).

However, even if a binary build for your platform of choice is not available, you can choose to stick with the generic pure-Python wheel (that pip should pick automatically), or cythonize Falcon for your environment (see instructions below). The pure-Python version is functionally identical to binary wheels; it is just slower on CPython.

Cythonizing Falcon#

Falcon leverages PEP 517 to automatically compile (AKA cythonize) itself with Cython whenever it is installed from the source distribution. So if a suitable binary wheel is unavailable for your platform, or if you want to recompile locally, you simply need to instruct pip not to use prebuilt wheels:

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

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

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

Apart from the obvious requirement to have a functional compiler toolchain set up with CPython development headers, the only inconvenience of running cythonization on your side is the extra couple of minutes it takes (depending on your hardware; it can take much more on an underpowered CI runner, or if you are using emulation to prepare your software for another architecture).

Furthermore, you can also cythonize the latest developmental snapshot Falcon directly from the source code on GitHub:

$ pip install git+https://github.com/falconry/falcon/

Danger

Although we try to keep the main development branch in a good shape at all times, we strongly recommend to use only stable versions of Falcon in production.

Compiling on Mac OS#

Tip

Pre-compiled Falcon wheels are available for macOS on both Intel and Apple Silicon chips, so normally you should be fine with just pip install falcon.

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, 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"

Binary Wheels#

Binary Falcon wheels are automatically built for many CPython platforms, courtesy of cibuildwheel.

The following table summarizes the wheel availability on different combinations of CPython versions vs CPython platforms:

Platform / CPython version

3.8

3.9

3.10

3.11

3.12

3.13

Linux Intel manylinux 64-bit

✅

✅

✅

✅

✅

✅

Linux Intel musllinux 64-bit

✅

✅

✅

✅

✅

✅

Linux Intel manylinux 32-bit

Linux Intel musllinux 32-bit

Linux ARM manylinux 64-bit

✅

✅

✅

✅

✅

Linux ARM musllinux 64-bit

✅

✅

✅

✅

✅

Linux PowerPC manylinux 64-bit

Linux PowerPC musllinux 64-bit

Linux IBM Z manylinux

✅

✅

✅

✅

✅

Linux IBM Z musllinux

macOS Intel

✅

✅

✅

✅

✅

macOS Apple Silicon

✅

✅

✅

✅

✅

Windows 32-bit

Windows 64-bit

✅

✅

✅

✅

✅

Windows ARM 64-bit

Warning

The free-threaded build flag is not yet enabled for our wheels at this time.

If you wish to experiment with running Falcon in the free-threaded mode, you will need to explicitly tell the interpreter to disable GIL (via the PYTHON_GIL environment variable, or the -X gil=0 option). It is also advisable to recompile Falcon from source on a free-threaded CPython 3.13+ build before proceeding. Let us know how it went!

While we believe that our build configuration covers the most common development and deployment scenarios, let us known if you are interested in any builds that are currently missing from our selection!

Dependencies#

Falcon does not require the installation of any other packages.

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.

Windows users can try Waitress, a production-quality, pure-Python WSGI server. Other alternatives on Windows include running Gunicorn and uWSGI via WSL, as well as inside Linux Docker containers.

$ pip install [gunicorn|uwsgi|waitress]

ASGI Server#

Conversely, in order to run an async Falcon ASGI app, you will need an ASGI application server (Falcon only supports ASGI 3.0+, aka the single-callable application style).

Uvicorn is a popular choice, owing to its fast and stable implementation. What is more, Uvicorn is supported on Windows, and on PyPy (however, both at a performance loss compared to CPython on Unix-like systems).

Falcon is also regularly tested against Daphne, the current ASGI reference server.

For a more in-depth overview of available servers, see also: ASGI Implementations.

$ pip install [uvicorn|daphne|hypercorn]

Note

By default, the uvicorn package comes only with a minimal set of pure-Python dependencies. For CPython-based production deployments, you can install Uvicorn along with more optimized alternatives such as uvloop (a faster event loop), httptools (a faster HTTP protocol implementation) etc:

$ pip install uvicorn[standard]

See also a longer explanation on Uvicorn’s website: Quickstart.

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:

$ # Clone over SSH:
$ #   git clone git@github.com:falconry/falcon.git
$ # Or, if you prefer, over HTTPS:
$ #   git clone https://github.com/falconry/falcon
$ cd falcon
$ pip install .

Tip

The above command will automatically install the cythonized version of Falcon. If you just want to experiment with the latest snapshot, you can skip the cythonization step by setting the FALCON_DISABLE_CYTHON environment variable to a non-empty value:

$ cd falcon
$ FALCON_DISABLE_CYTHON=Y 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 command 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
$ FALCON_DISABLE_CYTHON=Y 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
$ FALCON_DISABLE_CYTHON=Y pip install -e .
$ pip install -r requirements/tests
$ pytest tests

Or, to run the default set of tests:

$ pip install tox && tox

Tip

See also the tox.ini file for a full list of available environments.

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