.. raw:: html

<a href="https://falconframework.org" target="_blank">
<img
    src="https://raw.githubusercontent.com/falconry/falcon/master/logo/banner.jpg"
    alt="Falcon web framework logo"
    style="width:100%"
>
</a>

The Falcon Web Framework

Falcon <https://falconframework.org>__ is a minimalist ASGI/WSGI framework for building mission-critical REST APIs and microservices, with a focus on reliability, correctness, and performance at scale.

When it comes to building HTTP APIs, other frameworks weigh you down with tons of dependencies and unnecessary abstractions. Falcon cuts to the chase with a clean design that embraces HTTP and the REST architectural style.

Falcon apps work with any WSGI <https://www.python.org/dev/peps/pep-3333/>_ or ASGI <https://asgi.readthedocs.io/en/latest/>_ server, and run like a champ under CPython 3.8+ and PyPy 3.8+.

Quick Links

Read the docs <https://falcon.readthedocs.io/en/stable>_ (FAQ <https://falcon.readthedocs.io/en/stable/user/faq.html>_ - getting help <https://falcon.readthedocs.io/en/stable/community/help.html>_ - reference <https://falcon.readthedocs.io/en/stable/api/index.html>_)
Falcon add-ons and complementary packages <https://github.com/falconry/falcon/wiki>_
Falcon articles, talks and podcasts <https://github.com/falconry/falcon/wiki/Articles,-Talks-and-Podcasts>_
falconry/user for Falcon users <https://gitter.im/falconry/user>_ @ Gitter
falconry/dev for Falcon contributors <https://gitter.im/falconry/dev>_ @ Gitter

What People are Saying

"Falcon is rock solid and it's fast."

"We have been using Falcon as a replacement for [another framework] and we simply love the performance (three times faster) and code base size (easily half of our [original] code)."

"I'm loving #falconframework! Super clean and simple, I finally have the speed and flexibility I need!"

"Falcon looks great so far. I hacked together a quick test for a tiny server of mine and was ~40% faster with only 20 minutes of work."

"I feel like I'm just talking HTTP at last, with nothing in the middle. Falcon seems like the requests of backend."

"The source code for Falcon is so good, I almost prefer it to documentation. It basically can't be wrong."

"What other framework has integrated support for 786 TRY IT NOW ?"

Features

Falcon tries to do as little as possible while remaining highly effective.

ASGI, WSGI, and WebSocket support
Native asyncio support
No reliance on magic globals for routing and state management
Stable interfaces with an emphasis on backwards-compatibility
Simple API modeling through centralized RESTful routing
Highly-optimized, extensible code base
Easy access to headers and bodies through request and response classes
DRY request processing via middleware components and hooks
Strict adherence to RFCs
Idiomatic HTTP error responses
Straightforward exception handling
Snappy testing with WSGI/ASGI helpers and mocks
CPython 3.8+ and PyPy 3.8+ support

.. Patron list starts here. For Python package, we substitute this section with: Support Falcon Development

A Big Thank You to Our Patrons!

.. raw:: html

<p>
<a href="https://www.govcert.lu/" target="_blank"><img src="https://falconframework.org/assets/govcert.png" height="60" alt="CERT Gouvernemental Luxembourg" ></a>
 </p>

<p>
    <a href="https://www.kontrolnaya-rabota.ru/s/" target="_blank"><img src="https://falconframework.org/assets/rabota.jpg" height="30" alt="Examination RU" style="margin-right: 10px"></a>

    <a href="https://www.pnk.sh/python-falcon" target="_blank"><img src="https://falconframework.org/assets/paris.svg" height="30" alt="Paris Kejser" style="margin-right: 10px"></a>

    <a href="https://www.algolia.com" target="_blank" style="margin-right: 10px"><img src="https://falconframework.org/assets/algolia.svg" height="30" alt="Algolia"></a>

    <a href="https://www.salesforce.com" target="_blank"><img src="https://falconframework.org/assets/salesforce.svg" height="30" alt="Salesforce"></a>
</p>

<p>
    <a href="https://www.misaka.io" target="_blank" style="margin-right: 10px"><img src="https://falconframework.org/assets/misaka.svg" height="30" alt="Misaka Network"></a>
    <a href="https://github.com/LikaloLLC" target="_blank" style="margin-right: 10px"><img src="https://falconframework.org/assets/likalo.png" height="30" alt="Likalo"></a>
</p>

.. Patron list ends here (see the comment above this section).

Has Falcon helped you make an awesome app? Show your support today with a one-time donation or by becoming a patron. Supporters get cool gear, an opportunity to promote their brand to Python developers, and prioritized support.

Learn how to support Falcon development <https://falconframework.org/#sectionSupportFalconDevelopment>_

Thanks!

How is Falcon Different?

Perfection is finally attained not when there is no longer anything
to add, but when there is no longer anything to take away.

*- Antoine de Saint-Exupéry*

We designed Falcon to support the demanding needs of large-scale microservices and responsive app backends. Falcon complements more general Python web frameworks by providing bare-metal performance, reliability, and flexibility wherever you need it.

Reliable. We go to great lengths to avoid introducing breaking changes, and when we do they are fully documented and only introduced (in the spirit of SemVer <http://semver.org/>_) with a major version increment. The code is rigorously tested with numerous inputs and we require 100% coverage at all times. Falcon has no dependencies outside the standard library, helping minimize your app's attack surface while avoiding transitive bugs and breaking changes.

Debuggable. Falcon eschews magic. It's easy to tell which inputs lead to which outputs. Unhandled exceptions are never encapsulated or masked. Potentially surprising behaviors, such as automatic request body parsing, are well-documented and disabled by default. Finally, when it comes to the framework itself, we take care to keep logic paths simple and understandable. All this makes it easier to reason about the code and to debug edge cases in large-scale deployments.

Fast. Same hardware, more requests. Falcon turns around requests significantly faster than other popular Python frameworks like Django and Flask. For an extra speed boost, Falcon compiles itself with Cython when available, and also works well with PyPy <https://pypy.org>_. Considering a move to another programming language? Benchmark with Falcon+PyPy first!

Flexible. Falcon leaves a lot of decisions and implementation details to you, the API developer. This gives you a lot of freedom to customize and tune your implementation. It also helps you understand your apps at a deeper level, making them easier to tune, debug, and refactor over the long run. Falcon's minimalist design provides space for Python community members to independently innovate on Falcon add-ons and complementary packages <https://github.com/falconry/falcon/wiki>_.

Who's Using Falcon?

Falcon is used around the world by a growing number of organizations, including:

7ideas
Cronitor
EMC
Hurricane Electric
Leadpages
OpenStack
Rackspace
Shiftgig
tempfil.es
Opera Software

If you are using the Falcon framework for a community or commercial project, please consider adding your information to our wiki under Who's Using Falcon? <https://github.com/falconry/falcon/wiki/Who's-using-Falcon%3F>_

Community

A number of Falcon add-ons, templates, and complementary packages are available for use in your projects. We've listed several of these on the Falcon wiki <https://github.com/falconry/falcon/wiki>_ as a starting point, but you may also wish to search PyPI for additional resources.

The Falconry community on Gitter is a great place to ask questions and share your ideas. You can find us in falconry/user <https://gitter.im/falconry/user>. We also have a falconry/dev <https://gitter.im/falconry/dev> room for discussing the design and development of the framework itself.

Per our Code of Conduct <https://github.com/falconry/falcon/blob/master/CODEOFCONDUCT.md>_, we expect everyone who participates in community discussions to act professionally, and lead by example in encouraging constructive discussions. Each individual in the community is responsible for creating a positive, constructive, and productive culture.

Installation

PyPy ^^^^

PyPy <http://pypy.org/>__ is the fastest way to run your Falcon app. PyPy3.8+ is supported as of PyPy v7.3.7+.

.. code:: bash

$ pip install falcon

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

.. code:: bash

$ pip install --pre falcon

CPython ^^^^^^^

Falcon also fully supports CPython <https://www.python.org/downloads/>__ 3.8+.

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

.. code:: bash

$ pip install falcon

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

.. code:: bash

$ pip install --pre falcon

In order to provide an extra speed boost, Falcon can compile itself with Cython. Wheels containing pre-compiled binaries are available from PyPI for several common platforms. However, if a wheel for your platform of choice is not available, you can install the source distribution. The installation process will automatically try to cythonize Falcon for your environment, falling back to a normal pure-Python install if any issues are encountered during the cythonization step:

.. code:: bash

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

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

The cythonization step is only active when using the CPython Python implementation, so installing using PyPy will skip it. If you want to skip Cython compilation step and install the pure-Python version directly you can set the environment variable FALCON_DISABLE_CYTHON to a non empty value before install:

.. code:: bash

$ FALCON_DISABLE_CYTHON=Y pip install -v --no-binary :all: falcon

Please note that pip>=10 is required to be able to install Falcon from source.

Installing on OS X

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

.. code:: bash

$ xcode-select --install

The Clang compiler treats unrecognized command-line options as errors, for example:

.. code:: bash

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:

.. code:: bash

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

Dependencies ^^^^^^^^^^^^

Falcon does not require the installation of any other packages, although if Cython has been installed into the environment, it will be used to optimize the framework as explained above.

WSGI Server

Falcon speaks WSGI <https://www.python.org/dev/peps/pep-3333/>_ (or ASGI <https://asgi.readthedocs.io/en/latest/>_; see also below). 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.

.. code:: bash

$ pip install [gunicorn|uwsgi]

ASGI Server

In order to serve a Falcon ASGI app, you will need an ASGI server. Uvicorn is a popular choice:

.. code:: bash

$ pip install uvicorn

Source Code

Falcon lives on GitHub <https://github.com/falconry/falcon>_, 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:

.. code:: bash

$ 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:

.. code:: bash

$ 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:

.. code:: bash

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

Or, to run the default set of tests:

.. code:: bash

$ pip install tox && tox

See also the tox.ini <https://github.com/falconry/falcon/blob/master/tox.ini>_ file for a full list of available environments.

Read the Docs

The docstrings in the Falcon code base are quite extensive, and we recommend keeping a REPL running while learning the framework so that you can query the various modules and classes as you have questions.

Online docs are available at: https://falcon.readthedocs.io

You can build the same docs locally as follows:

.. code:: bash

$ 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:

.. code:: bash

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

Getting Started

Here is a simple, contrived example showing how to create a Falcon-based WSGI app (the ASGI version is included further down):

.. code:: python

# examples/things.py

# Let's get this party started!
from wsgiref.simple_server import make_server

import falcon


# Falcon follows the REST architectural style, meaning (among
# other things) that you think in terms of resources and state
# transitions, which map to HTTP verbs.
class ThingsResource:
    def on_get(self, req, resp):
        """Handles GET requests"""
        resp.status = falcon.HTTP_200  # This is the default status
        resp.content_type = falcon.MEDIA_TEXT  # Default is JSON, so override
        resp.text = ('\nTwo things awe me most, the starry sky '
                     'above me and the moral law within me.\n'
                     '\n'
                     '    ~ Immanuel Kant\n\n')


# falcon.App instances are callable WSGI apps...
# in larger applications the app is created in a separate file
app = falcon.App()

# Resources are represented by long-lived class instances
things = ThingsResource()

# things will handle all requests to the '/things' URL path
app.add_route('/things', things)

if __name__ == '__main__':
    with make_server('', 8000, app) as httpd:
        print('Serving on port 8000...')

        # Serve until process is killed
        httpd.serve_forever()

You can run the above example directly using the included wsgiref server:

.. code:: bash

$ pip install falcon
$ python things.py

Then, in another terminal:

.. code:: bash

$ curl localhost:8000/things

The ASGI version of the example is similar:

.. code:: python

# examples/things_asgi.py

import falcon
import falcon.asgi


# Falcon follows the REST architectural style, meaning (among
# other things) that you think in terms of resources and state
# transitions, which map to HTTP verbs.
class ThingsResource:
    async def on_get(self, req, resp):
        """Handles GET requests"""
        resp.status = falcon.HTTP_200  # This is the default status
        resp.content_type = falcon.MEDIA_TEXT  # Default is JSON, so override
        resp.text = ('\nTwo things awe me most, the starry sky '
                     'above me and the moral law within me.\n'
                     '\n'
                     '    ~ Immanuel Kant\n\n')


# falcon.asgi.App instances are callable ASGI apps...
# in larger applications the app is created in a separate file
app = falcon.asgi.App()

# Resources are represented by long-lived class instances
things = ThingsResource()

# things will handle all requests to the '/things' URL path
app.add_route('/things', things)

You can run the ASGI version with uvicorn or any other ASGI server:

.. code:: bash

$ pip install falcon uvicorn