FastAPI on AWS Lambda: Deploy with Mangum & API Gateway

How it works in plain terms

When someone calls your API, the request travels through this chain:

1. HTTP request arrives at your API Gateway HTTP API endpoint (e.g. https://YOUR-API-ID.execute-api.us-east-1.amazonaws.com/items/42)
2. API Gateway receives the request, applies any configured auth or throttling, and converts it into a Lambda event payload
3. Lambda receives the event and passes it to your handler function
4. Mangum receives the Lambda event and translates it into an ASGI-format request that FastAPI understands
5. FastAPI processes the request, validates inputs, runs your route handler, and builds a response
6. Mangum converts the FastAPI response back into a Lambda response format, and API Gateway returns it as an HTTP response

Lambda is stateless. Each invocation runs in an execution environment that may be new (cold start) or reused from a previous request (warm start). In-memory data does not persist reliably across invocations and is not shared between concurrent executions. Real application data such as user records, items, or sessions must live in an external store like DynamoDB or RDS.

When to use FastAPI on Lambda

Lambda is a strong fit when:

• Traffic is variable, bursty, or unpredictable. You pay per request, not for idle time.
• You want zero server management and automatic scaling without configuring Auto Scaling Groups
• Request handlers complete quickly, typically under a few seconds, well within the 15-minute limit
• You are building internal tools, webhooks, lightweight APIs, or microservices with moderate throughput
• You want to prototype quickly and only pay when the API is actually used

When not to use Lambda

• Long-running jobs. Lambda has a 15-minute hard limit per invocation. Use AWS Batch or Step Functions instead.
• Always-on high-throughput APIs. If your API handles thousands of requests per second around the clock, ECS or EC2 is cheaper. Per-invocation overhead adds up at sustained scale.
• Heavy dependency sets. If your app requires pandas, numpy, or large ML libraries, package size and cold starts become serious problems. Consider container images or move to App Runner.
• WebSocket or persistent connections. Lambda is request-response only. It cannot hold open connections. Use API Gateway WebSocket APIs with DynamoDB for connection state, or consider ECS.
• Ultra-low-latency on every request. Cold starts add latency. Provisioned concurrency helps but adds cost. Evaluate whether ECS Fargate gives better predictability for your SLA.

For a structured comparison of these options, see the Lambda vs ECS vs EC2 decision guide.

Architecture overview

The standard setup uses API Gateway HTTP API (v2) as the public endpoint and a single Lambda function running your entire FastAPI app:

Internet → API Gateway HTTP API → Lambda function
                                     └── Mangum adapter
                                           └── FastAPI app
                                                 └── Your route handlers

API Gateway handles TLS termination, throttling, and optional auth. Lambda handles the compute. Mangum bridges Lambda’s event format and FastAPI’s ASGI interface.

API Gateway HTTP API vs Lambda Function URL

You have two options for giving your Lambda function an HTTP endpoint:

This guide uses API Gateway HTTP API as the main walkthrough. For simpler use cases such as a webhook handler or an internal API, a Lambda Function URL gives you a direct HTTPS endpoint with far less configuration.

Prerequisites

• AWS account with permissions to create Lambda functions, IAM roles, and API Gateway APIs
• AWS CLI installed and configured (aws configure)
• Python 3.12 installed locally
• Basic familiarity with FastAPI. This guide does not cover FastAPI fundamentals.
• An IAM execution role for Lambda with at least AWSLambdaBasicExecutionRole attached. See the first Lambda function guide for the full IAM setup.

Project structure

my-fastapi-lambda/
├── app/
│   ├── __init__.py
│   ├── main.py        ← FastAPI application
│   └── routes/
│       └── items.py
├── lambda_handler.py  ← Lambda entry point (Mangum wrapper)
├── requirements.txt
└── build.sh           ← Packaging script

Keep lambda_handler.py separate from your app code. Lambda’s handler setting points to this file (lambda_handler.handler), not to your FastAPI app directly.

Minimal FastAPI app

Write a standard FastAPI app in app/main.py. The example below uses an in-memory dict as a demo stand-in for a real data store. It is fine for local testing but not for production.

# app/main.py

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional

app = FastAPI(
    title="My Lambda API",
    description="FastAPI running on AWS Lambda",
    version="1.0.0"
)

class Item(BaseModel):
    name: str
    price: float
    description: Optional[str] = None

# Demo only: this in-memory store is lost when the execution environment is
# recycled and is NOT shared across concurrent Lambda executions.
# Replace with DynamoDB or another external store in production.
items: dict = {}

@app.get("/")
def root():
    return {"message": "FastAPI on Lambda is working"}

@app.get("/health")
def health():
    return {"status": "healthy"}

@app.get("/items/{item_id}")
def get_item(item_id: str):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")
    return items[item_id]

@app.post("/items/{item_id}")
def create_item(item_id: str, item: Item):
    items[item_id] = item.model_dump()  # Pydantic v2: model_dump() replaces .dict()
    return {"message": "Item created", "item_id": item_id}

Lambda handler with Mangum

Create lambda_handler.py at the project root. This is the file Lambda calls when a request arrives:

# lambda_handler.py

from mangum import Mangum
from app.main import app

# lifespan="off" disables ASGI startup/shutdown events, which Lambda does not support.
# Any initialisation logic (DB clients, config loading) should be at module level,
# outside any function, so it runs once per execution environment.
handler = Mangum(app, lifespan="off")

The lifespan=“off” parameter is important. By default, Mangum tries to run ASGI lifespan events (startup/shutdown). Lambda does not support these because each invocation is independent and stateless. Setting lifespan=“off” skips them cleanly. If you use FastAPI’s @app.on_event(“startup”) hooks, move that logic to module-level code instead (outside any function definition), so it runs once when the execution environment initialises.

Dependencies and packaging

requirements.txt

Pin exact versions for deterministic builds. Use pip-tools or pip freeze to generate a locked file from your development environment:

fastapi==0.110.0
mangum==0.17.0
pydantic==2.6.0

Building the ZIP package

Lambda’s ZIP deployment requires your code and all dependencies bundled together. This script installs dependencies into a staging directory and zips everything:

#!/bin/bash
# build.sh

set -e

rm -rf dist/
mkdir dist/

# Install dependencies flat into dist/
pip install -r requirements.txt -t dist/ --quiet

# Copy application code
cp -r app/ dist/
cp lambda_handler.py dist/

# Create zip, excluding compiled bytecode
cd dist
zip -r ../function.zip . -x "*.pyc" -x "*/__pycache__/*"
cd ..

echo "Build complete: function.zip ($(du -sh function.zip | cut -f1))"

chmod +x build.sh && ./build.sh

Check the output size. FastAPI, Mangum, and Pydantic v2 together total around 15 to 20 MB unzipped, well under Lambda’s 250 MB unzipped limit.

ZIP vs container image

ZIP packages are simpler and deploy faster. Switch to a container image (via ECR and Lambda container image support) when:

• Your unzipped dependencies exceed 250 MB, which is common when adding pandas, numpy, or scikit-learn
• You need a specific system-level dependency such as shared libraries or custom binaries
• You want a fully reproducible, version-controlled build environment

Container images support up to 10 GB, but larger images mean longer cold starts. Keep images lean by using multi-stage Docker builds and avoiding dev dependencies in the final image.

Deployment walkthrough

Step 1: Create the Lambda function

Replace the ARN with your actual IAM execution role ARN (see the first Lambda guide for role creation):

aws lambda create-function \
  --function-name fastapi-app \
  --runtime python3.12 \
  --role arn:aws:iam::123456789012:role/MyLambdaExecutionRole \
  --handler lambda_handler.handler \
  --zip-file fileb://function.zip \
  --timeout 30 \
  --memory-size 256 \
  --environment "Variables={ENVIRONMENT=production}"

aws lambda wait function-active --function-name fastapi-app

Step 2: Test the function directly

Before connecting API Gateway, verify the function responds correctly by simulating an API Gateway HTTP API event payload:

aws lambda invoke \
  --function-name fastapi-app \
  --cli-binary-format raw-in-base64-out \
  --payload '{
    "version": "2.0",
    "routeKey": "GET /",
    "rawPath": "/",
    "rawQueryString": "",
    "headers": {"content-type": "application/json"},
    "requestContext": {
      "http": {"method": "GET", "path": "/", "protocol": "HTTP/1.1"}
    },
    "isBase64Encoded": false
  }' \
  response.json

cat response.json
# Expected: {"statusCode":200,"body":"{\"message\":\"FastAPI on Lambda is working\"}","headers":...}

Step 3: Create an API Gateway HTTP API

Create the API and capture the ID. You need it for subsequent commands:

API_ID=$(aws apigatewayv2 create-api \
  --name fastapi-http-api \
  --protocol-type HTTP \
  --query "ApiId" \
  --output text)

echo "API ID: $API_ID"

Step 4: Create the Lambda integration

Set payload format version 2.0. This is what Mangum expects from API Gateway HTTP API:

INTEGRATION_ID=$(aws apigatewayv2 create-integration \
  --api-id $API_ID \
  --integration-type AWS_PROXY \
  --integration-uri arn:aws:lambda:us-east-1:123456789012:function:fastapi-app \
  --payload-format-version "2.0" \
  --query "IntegrationId" \
  --output text)

Step 5: Add routes and deploy to a stage

Add a catch-all route to forward all paths to the Lambda function, then create a prod stage with auto-deploy enabled:

# Catch-all route for all methods and sub-paths
aws apigatewayv2 create-route \
  --api-id $API_ID \
  --route-key "ANY /{proxy+}" \
  --target "integrations/$INTEGRATION_ID"

# Root route
aws apigatewayv2 create-route \
  --api-id $API_ID \
  --route-key "ANY /" \
  --target "integrations/$INTEGRATION_ID"

# Deploy to a stage
aws apigatewayv2 create-stage \
  --api-id $API_ID \
  --stage-name prod \
  --auto-deploy

Step 6: Grant API Gateway permission to invoke Lambda

Without this resource-based policy, API Gateway will receive a 500 when it tries to call your function:

aws lambda add-permission \
  --function-name fastapi-app \
  --statement-id api-gateway-invoke \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:us-east-1:123456789012:$API_ID/*/*"

Step 7: Get the public endpoint URL

aws apigatewayv2 get-api \
  --api-id $API_ID \
  --query "ApiEndpoint" \
  --output text
# https://YOUR-API-ID.execute-api.us-east-1.amazonaws.com

Testing your deployment

Test the public endpoint with curl:

# Root endpoint
curl https://YOUR-API-ID.execute-api.us-east-1.amazonaws.com/
# {"message":"FastAPI on Lambda is working"}

# Health check
curl https://YOUR-API-ID.execute-api.us-east-1.amazonaws.com/health
# {"status":"healthy"}

# Create an item (POST)
curl -X POST https://YOUR-API-ID.execute-api.us-east-1.amazonaws.com/items/widget1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Widget", "price": 9.99}'
# {"message":"Item created","item_id":"widget1"}

# Retrieve that item
curl https://YOUR-API-ID.execute-api.us-east-1.amazonaws.com/items/widget1
# {"name":"Widget","price":9.99,"description":null}

FastAPI’s auto-generated interactive docs are available at /docs. Open https://YOUR-API-ID.execute-api.us-east-1.amazonaws.com/docs in a browser to verify all routes are visible and responding. The Swagger UI is a useful sanity check that Mangum is routing requests correctly and FastAPI is parsing the payload format properly.

Production considerations

Cold starts

A minimal FastAPI app with Pydantic v2 cold-starts in roughly 500ms to 1 second. This is acceptable for many use cases. Cold starts get worse as dependencies grow because each additional library adds initialisation time. To manage cold starts:

• Keep requirements.txt lean. Only include what your app actually uses.
• Prefer Pydantic v2 over v1 (significantly faster startup and validation)
• Move heavy initialisation such as DB client creation and config loading to module level. It runs once per execution environment, not once per request.
• Use provisioned concurrency for latency-sensitive endpoints. It keeps execution environments pre-warmed and eliminates cold starts entirely. See Lambda scaling and concurrency.

Persistence and databases

Lambda is stateless. Never rely on in-memory structures for application data. Use external storage appropriate to your data model:

• DynamoDB is the natural fit for Lambda. It is serverless, scales alongside your function, has no connection limit problems, and has no idle cost.
• RDS with RDS Proxy for relational data. Without RDS Proxy, concurrent Lambda executions each open their own database connection. At 200 concurrent executions that is 200 simultaneous connections, which exhausts most small RDS instances. RDS Proxy pools connections between Lambda and the database so this does not happen.
• ElastiCache for caching. Requires VPC access, which adds some cold start latency.

Security and auth

Before going to production, read the Lambda security model and add at least one auth layer:

• API Gateway JWT authorizer validates JWTs from Cognito or another IdP before Lambda is ever invoked
• FastAPI middleware handles auth inside your app (API key checking, OAuth2, etc.)
• IAM auth for internal AWS service-to-service calls where the caller can sign requests

Store sensitive configuration such as DB passwords, API keys, and secrets in AWS Secrets Manager or SSM Parameter Store. Do not hardcode them in environment variables or source code.

Logging and monitoring

Lambda automatically captures stdout and stderr to CloudWatch Logs. Use Python’s standard logging module rather than print statements. Structured log output is easier to filter and query. For production observability, see monitoring Lambda with CloudWatch.

import logging
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

@app.get("/items/{item_id}")
def get_item(item_id: str):
    logger.info("Fetching item %s", item_id)
    ...

Cost control

Lambda pricing is based on request count and duration in GB-seconds. FastAPI functions are typically fast, so cost is usually low. To keep it predictable:

• Right-size memory. More memory also means more CPU, which can reduce execution duration and lower total cost. Test at 128 MB, 256 MB, and 512 MB to find the sweet spot for your workload.
• Set reasonable timeouts. The default is 3 seconds. Set it to something appropriate for your app rather than the maximum 15 minutes. Stuck invocations should fail fast, not accumulate cost.
• Avoid unnecessary invocations. Health check endpoints that trigger expensive operations run up your bill quickly when polled by a load balancer every few seconds.

See Lambda cost optimisation for a deeper look at pricing and memory tuning.

Infrastructure and deployment tooling

The AWS CLI walkthrough in this guide is good for understanding how things work, but for team development you want repeatable infrastructure. Consider AWS SAM (purpose-built for Lambda), Terraform, or AWS CDK. If your app has grown beyond Lambda’s sweet spot due to large dependencies, sustained traffic, or complex connection requirements, evaluate App Runner or ECS Fargate. Both run a containerised FastAPI app without Lambda’s constraints.

FastAPI on Lambda vs other AWS options

Lambda is one of several ways to run a FastAPI app on AWS. The right choice depends on your traffic pattern, latency requirements, and how much operational overhead you want.

See the Lambda vs ECS comparison, the Lambda vs EC2 comparison, and the App Runner overview for more detail on each path.