{"id":4531,"library":"falcon","title":"Falcon Web Framework","description":"Falcon is a minimalist, high-performance Python web API framework for building REST APIs and microservices. It provides a clean design that embraces HTTP and the REST architectural style, with a strong focus on reliability, correctness, and speed. The current version, 4.2.0, primarily contains typing enhancements and performance optimizations, including support for free-threaded CPython 3.14. Falcon supports both synchronous (WSGI) and asynchronous (ASGI) applications and typically follows a stable release cadence with regular updates.","status":"active","version":"4.2.0","language":"python","source_language":"en","source_url":"https://github.com/falconry/falcon","tags":["web-framework","asgi","wsgi","api","rest","microservices","performance"],"install":[{"cmd":"pip install falcon","lang":"bash","label":"Install Falcon"}],"dependencies":[],"imports":[{"note":"While `from falcon import App` works, the idiomatic way for WSGI apps is `import falcon; app = falcon.App()` as `falcon` is the primary module. For ASGI apps, use `from falcon.asgi import App as ASGIApp`.","wrong":"from falcon import App","symbol":"App","correct":"import falcon\napp = falcon.App()"},{"note":"For building asynchronous (ASGI) applications, import `App` specifically from `falcon.asgi` and alias it to avoid collision with the WSGI `App`.","symbol":"ASGIApp","correct":"from falcon.asgi import App as ASGIApp\napp = ASGIApp()"},{"note":"Commonly imported for type hinting in responder methods (e.g., `def on_get(self, req: Request, resp: Response):`).","symbol":"Request","correct":"from falcon import Request, Response"},{"note":"Commonly imported for type hinting in responder methods (e.g., `def on_get(self, req: Request, resp: Response):`).","symbol":"Response","correct":"from falcon import Request, Response"},{"note":"HTTP status codes are exposed directly on the `falcon` module (e.g., `falcon.HTTP_200`, `falcon.HTTP_201`).","symbol":"HTTP_200","correct":"import falcon\nresp.status = falcon.HTTP_200"}],"quickstart":{"code":"import falcon\n\nclass QuoteResource:\n    def on_get(self, req: falcon.Request, resp: falcon.Response) -> None:\n        \"\"\"Handles GET requests.\"\"\"\n        resp.status = falcon.HTTP_200\n        resp.media = {\n            'quote': \"I've always been more interested in the future than in the past.\",\n            'author': 'Grace Hopper',\n        }\n\n# Instantiate a WSGI Falcon application\napp = falcon.App()\n\n# Create an instance of our resource\nquotes = QuoteResource()\n\n# Add a route to our application\napp.add_route('/quote', quotes)\n\n# To run this, save as `app.py` and then run:\n# pip install gunicorn\n# gunicorn app:app\n# Then access via curl: curl http://127.0.0.1:8000/quote","lang":"python","description":"This quickstart demonstrates a simple WSGI Falcon application. It defines a resource with an `on_get` method to handle GET requests to the `/quote` endpoint, returning a JSON response. The `falcon.App()` instance is then created and the resource is attached to a route. To serve this application, a WSGI server like Gunicorn is typically used. For ASGI applications, `falcon.asgi.App` and `async` responder methods would be used."},"warnings":[{"fix":"Upgrade your Python environment to 3.9+ and carefully review the Falcon 4.0 changelog for specific removals and breaking changes. Pay attention to deprecation warnings when upgrading from 3.x to 4.x.","message":"Falcon 4.0 dropped support for Python 3.5-3.7. Applications must use Python 3.8 or newer (Falcon 4.2.0 requires Python 3.9+). It also removed many functions, classes, and compatibility shims previously deprecated in the 3.x series.","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Review your application's media type handling, especially if you rely on `req.client_prefers` or custom media handlers. Ensure your media types and their parameters are parsed as expected.","message":"Falcon 4.0 changed the behavior of media type parsing, specifically regarding the vendored `python-mimeparse` library and `req.client_prefers`. It also changed how media types with different values for the same parameters are considered.","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Ensure that your resource classes are thread-safe. Avoid storing mutable per-request state directly as instance attributes on the resource. Instead, use `req` and `resp` objects for per-request data, or ensure proper synchronization if shared state is intentionally modified.","message":"A single instance of each resource class is shared among all requests processed by a given worker. This means that any instance variables on your resource classes are shared across concurrent requests.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `req.get_media()` or `req.media` (for common types) or `req.stream` to read the request body in your responders. For example, `data = req.get_media()` to parse JSON or form data.","message":"Falcon does not automatically consume request bodies. For `application/json` or `application/x-www-form-urlencoded` content types, you must explicitly call `req.get_media()` or access `req.media` to parse the body. For other content types or direct stream access, use `req.stream`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement custom error handlers using `app.add_error_handler()` for specific exception types you wish to handle differently, or for a general `Exception` to override the default 500 behavior.","message":"As of Falcon 3.0, uncaught exceptions that do not inherit from `falcon.HTTPError` or `falcon.HTTPStatus` will no longer propagate to the application server. Instead, a default `HTTP 500` response will be returned, and details will be logged to `wsgi.errors`.","severity":"deprecated","affected_versions":"3.0.0 and later"}],"env_vars":null,"search_vec":"'3.14':61 '4.2.0':46 'api':13,18,86 'applic':70 'architectur':32 'asgi':69,84 'asynchron':68 'build':16 'cadenc':77 'clean':24 'contain':48 'correct':40 'cpython':60 'current':44 'design':25 'embrac':27 'enhanc':50 'falcon':1,4,62 'focus':37 'follow':73 'framework':3,14,83 'free':58 'free-thread':57 'high':9 'high-perform':8 'http':28 'includ':54 'microservic':20,88 'minimalist':7 'optim':53 'perform':10,52,89 'primarili':47 'provid':22 'python':11 'regular':79 'releas':76 'reliabl':39 'rest':17,31,87 'speed':42 'stabl':75 'strong':36 'style':33 'support':55,63 'synchron':65 'thread':59 'type':49 'typic':72 'updat':80 'version':45 'web':2,12,82 'web-framework':81 'wsgi':66,85","created_at":"2026-04-12T13:56:38.367220+00:00","updated_at":"2026-04-16T14:55:43.415095+00:00","problems":[{"fix":"Ensure Falcon is installed using `pip install falcon`. If a script is named `falcon.py`, rename it to avoid conflict. If using virtual environments, ensure the correct environment is activated.","cause":"The 'falcon' package is not installed in the Python environment being used, or the Python interpreter cannot find it. This can also happen if a user's script is named `falcon.py`, shadowing the actual library.","error":"ModuleNotFoundError: No module named 'falcon'"},{"fix":"Rename your Python file from `falcon.py` to something else (e.g., `app.py` or `main.py`) to prevent it from shadowing the installed `falcon` module.","cause":"This error typically occurs when a user's Python file is named `falcon.py`, causing Python to import the user's file instead of the Falcon framework, which then lacks the `API` attribute.","error":"AttributeError: 'module' object has no attribute 'API'"},{"fix":"Decode the bytes read from the request stream into a string before passing it to `json.loads()`. Alternatively, for common media types, use `req.media` or `req.get_media()` which handles decoding automatically.","cause":"When parsing a request body as JSON, `json.loads()` expects a string, but the `req.stream.read()` method (or `req.bounded_stream.read()`) returns bytes in Python 3.","error":"TypeError: the JSON object must be str, not 'bytes'"},{"fix":"Modify the URI templates to be unique and unambiguous. This often involves adjusting base paths or parameter definitions to ensure no two routes can match the same incoming URL.","cause":"Two or more routes defined in the Falcon application have overlapping or identical URI templates, leading to ambiguity in how requests should be dispatched.","error":"ValueError: The URI template for this route conflicts with another route's template."},{"fix":"Upgrade your Falcon installation to a version compatible with your Python interpreter, or downgrade your Python version to one supported by the older Falcon release. Falcon 4.0 and later require Python 3.9+.","cause":"This error can occur when trying to install or run older versions of Falcon (e.g., 3.1.3) with newer Python versions (e.g., Python 3.13), where there might be a change in how `setuptools` or Python itself expects to find module metadata.","error":"AttributeError: module 'falcon' has no attribute '__version__'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.3.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://falconframework.org","github":"https://github.com/falconry/falcon","docs":"https://falcon.readthedocs.io/en/stable/","changelog":"https://falcon.readthedocs.io/en/stable/changes/","pypi":"https://pypi.org/project/falcon/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}