mangum

library0.22.0pypypi✓ verified 24d ago

Mangum is an adapter designed to run ASGI (Asynchronous Server Gateway Interface) applications, such as FastAPI, Starlette, Quart, and Django, within AWS Lambda environments. It handles various AWS event types including Function URLs, API Gateway (HTTP and REST APIs), Application Load Balancer, and CloudFront Lambda@Edge. The library is actively maintained, with frequent releases, and is currently at version 0.21.0.

aws web-framework

pip install mangum

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · MANGUM

mangum

awspythonv0.22.0

Install

1.6s avg

Import

224ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.22.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.238s · 18.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.210s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Mangum

✓ from mangum import Mangum

This quickstart demonstrates how to wrap a simple FastAPI application with Mangum to make it deployable as an AWS Lambda function. The `handler` object is the entry point for AWS Lambda, which Mangum uses to convert Lambda events into ASGI requests for your application.

from fastapi import FastAPI from mangum import Mangum app = FastAPI() @app.get("/hello") async def read_root(): return {"message": "Hello from FastAPI on Lambda!"} handler = Mangum(app) # To test locally, you would typically run with uvicorn: # uvicorn main:app --reload --port 8000 # For Lambda, `handler` is the entry point defined in your function configuration.

Debug

Known issues

breakingMangum dropped official support for Python 3.7 and Python 3.8 in version 0.20.0. Applications targeting these Python versions should remain on an older Mangum release (e.g., 0.19.0 or earlier) or upgrade their Python runtime to 3.9 or newer.

fix

Upgrade your Python runtime to 3.9 or later or pin your Mangum dependency to `<0.20.0`.

affects: >=0.20.0

gotchaWhen deploying FastAPI applications behind AWS API Gateway with custom base paths or stages, incorrect routing ('not found' errors) can occur. It's often necessary to configure `api_gateway_base_path` in the Mangum handler and/or `root_path` in your FastAPI app to match the API Gateway setup.

fix

Initialize Mangum with `handler = Mangum(app, api_gateway_base_path="/your/stage/path")` and configure your FastAPI app with `app = FastAPI(root_path="/your/stage/path")` as needed.

affects: All versions

gotchaThe `lifespan` parameter (defaulting to `"off"` in many examples) controls the ASGI lifespan events (startup/shutdown). Setting it to `"on"` or `"auto"` is crucial for applications that require startup tasks (e.g., database connections) or shutdown cleanup. Using `"off"` will prevent these events from running.

fix

Set `lifespan="on"` for explicit lifespan management or `lifespan="auto"` if your application framework supports it and you want Mangum to automatically handle it.

affects: All versions

deprecatedVersion 0.21.0 has introduced a `DeprecationWarning` related to `asyncio.get_event_loop` during Mangum initialization, indicating a potential shift in how event loops are managed or accessed. While currently a warning, it may foreshadow future breaking changes.

fix

Monitor Mangum's GitHub issues and releases for updates regarding asyncio event loop management and potential migration steps.

affects: 0.21.0

gotchaHandling binary media types (e.g., images, PDFs) or certain text-based content types (e.g., `application/json` with specific charsets) requires careful configuration to prevent data corruption. Headers like `Content-Type` might need explicit handling or inclusion in `text_mime_types` for proper encoding/decoding.

fix

Consult Mangum's documentation on `text_mime_types` and `exclude_headers` parameters to correctly configure how different content types are processed.

affects: All versions

Errors

Common errors & fixes

{ "detail": "Not Found" }

This error typically occurs when a FastAPI application deployed with Mangum on AWS Lambda cannot correctly route requests due to misconfigured API Gateway proxy integration, an incorrect base path, or missing trailing slashes in FastAPI routes.

fix

Ensure your API Gateway is configured with a proxy integration (`/{proxy+}`) and that the Mangum handler is initialized with `api_gateway_base_path` if your API Gateway has a base path. Also, set the `root_path` when creating your FastAPI app and consider adding routes for both trailing and non-trailing slashes.

"errorMessage": "The adapter was unable to infer a handler to use for the event. This is likely related to how the Lambda function was invoked. (Are you testing locally? Make sure the request payload is valid for a supported handler.)"

Mangum receives an AWS Lambda event that it cannot recognize or process, often due to an improperly formatted test event when testing locally, or an unsupported event source configuration in AWS Lambda.

fix

When testing locally, ensure your test event payload mimics a valid AWS event type (e.g., API Gateway HTTP API v2.0 event). When deploying, verify that the Lambda function's trigger (e.g., API Gateway, Function URL) is sending a compatible event structure to Mangum. Ensure your `lambda_handler` in `main.py` (or similar) is correctly defined as `handler = Mangum(app)`.

KeyError: 'requestContext'

This error arises when the AWS Lambda event object passed to Mangum is missing the expected `requestContext` key, which is essential for Mangum to construct the ASGI scope for the application. This often happens with non-standard Lambda invocations or when the event payload is incomplete.

fix

Ensure that your Lambda function is invoked with a full proxy integration from API Gateway, which provides the necessary `requestContext` in the event payload. If invoking directly, provide a mock event that includes a `requestContext` dictionary with relevant fields.

Runtime.ImportModuleError: Unable to import module 'app' (or similar, e.g., 'main')

This is a common AWS Lambda deployment error indicating that the specified handler file or module cannot be found or imported by the Lambda runtime. It's often due to incorrect file structure, incorrect handler name in Lambda configuration, or missing dependencies in the deployment package.

fix

Verify that your Python application file (e.g., `app.py` or `main.py`) is at the root of your deployment package, or that your handler path (e.g., `app.handler` or `main.lambda_handler`) correctly reflects your file and handler function name. Ensure all necessary dependencies (including `mangum`) are included in your deployment package.

Upgrade

Version history

0.22.0latest on PyPI · released Aug 22, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.9 or newer.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/Kludex/mangum ↗

packagehttps://pypi.org/project/mangum/ ↗

homepagehttps://mangum.io/ ↗

docshttps://mangum.fastapiexpert.com ↗

changeloghttps://github.com/Kludex/mangum/blob/main/CHANGELOG.md ↗