Zappa

0.62.1 · active · verified Thu Apr 16

Zappa is a Python library that simplifies the deployment of serverless Python web applications (WSGI and ASGI-compatible frameworks like Flask, Django, FastAPI, Bottle, Starlette, Quart) on AWS Lambda and API Gateway. It handles packaging the application and its virtual environment, configuring IAM roles, setting up API Gateway routes, and managing deployments to various stages. It is currently at version 0.62.1 and maintains an active release cadence.

Common errors

```
Unzipped size must be smaller than 262144000 bytes
```
cause Your Zappa package (including all dependencies) exceeds the AWS Lambda deployment package size limit (250MB unzipped).

fix Use Zappa's `slim_handler: true` setting in your `zappa_settings.json` to store large packages on S3 and load them at runtime, or consider using Docker-based deployments for larger projects with `docker_image_uri`.
```
An error occurred (AccessDeniedException) when calling the CreateFunction operation: User: arn:aws:iam::xxxxxxxxxxxx:user/your-user is not authorized to perform: lambda:CreateFunction on resource: arn:aws:lambda:us-east-1:xxxxxxxxxxxx:function:your-function-name
```
cause The AWS IAM user or role configured in your AWS credentials or `zappa_settings.json` lacks the necessary permissions to create or modify Lambda functions and related AWS resources.

fix Grant broader permissions (e.g., AdministratorAccess for testing) to your AWS user/role or specify a custom IAM policy that includes actions like `lambda:*`, `apigateway:*`, `s3:*`, and `iam:PassRole`. Ensure `profile_name` in `zappa_settings.json` refers to a profile with adequate permissions.
```
OSError: Stack creation failed. Please check your CloudFormation console.
```
cause Zappa failed to create or update the AWS CloudFormation stack that manages your Lambda and API Gateway resources. This is often due to underlying permission issues, resource limits, or incorrect configuration.

fix Run `zappa tail <stage>` to view CloudWatch logs for more detailed error messages. Check your AWS CloudFormation console for the specific stack (`<project_name>-<stage>`) to see failure reasons. If the issue persists, try `zappa undeploy <stage>` and then `zappa deploy <stage>` again after correcting any detected problems.
```
ImportError: No module named 'your_app_module'
```
cause Zappa failed to include your main application directory in the deployment package, or your `app_function` path in `zappa_settings.json` is incorrect. A common cause is the virtual environment having the same name as your project directory.

fix Verify that your `app_function` in `zappa_settings.json` (e.g., `my_project.app`) correctly points to your WSGI/ASGI application. If your virtual environment name matches your project directory name, rename the virtual environment.
```
DisallowedHost at / Invalid HTTP_HOST header: 'xxxxxxxx.execute-api.us-east-1.amazonaws.com'. You may need to add 'xxxxxxxx.execute-api.us-east-1.amazonaws.com' to ALLOWED_HOSTS.
```
cause This is a Django-specific security error where the host header from API Gateway (or a custom domain) is not listed in your Django project's `ALLOWED_HOSTS` setting.

fix Add the API Gateway execution URL (or your custom domain) to your Django `settings.py`'s `ALLOWED_HOSTS` list. For example, `ALLOWED_HOSTS = ['.execute-api.<region>.amazonaws.com', '.yourcustomdomain.com']`.

Warnings

breaking Zappa 0.61.0 removed deprecated `pkg_resource` usage and refactored internal `kappa` usage. While direct impact on end-user configuration might be minimal, custom Zappa client libraries or advanced configurations relying on these internal components may break.
Fix: Review Zappa's changelog for 0.61.0 and update any custom scripts or configurations that might have depended on `pkg_resource` or internal `kappa` constructs. Most direct users of the CLI should not be affected.
gotcha Deployments using AWS Lambda Function URLs (introduced in 0.61.0) might require additional IAM permissions. Deployments may fail or the function URL may not be accessible if these permissions are missing.
Fix: Ensure your Lambda execution role has the necessary `lambda:InvokeFunctionUrl` permission, specifically if using function URLs. Zappa attempts to manage roles, but manual adjustments might be needed for complex policies or when `manage_roles` is set to `false` in `zappa_settings.json`.
gotcha The virtual environment name should not be the same as your Zappa project's root directory name. This can cause Zappa to fail to package your application code correctly, leading to `ModuleNotFoundError` or other runtime issues on Lambda.
Fix: Rename your virtual environment (e.g., `venv`, `.venv`) so its name does not conflict with your main project directory's name.
gotcha Deploying Python applications with C-extension dependencies (e.g., NumPy, Pandas, Scikit-learn) on different architectures (e.g., Apple M1) than AWS Lambda (Amazon Linux) can lead to `ImportError` or `ModuleNotFoundError` at runtime on Lambda.
Fix: Use a Docker container with a Linux environment (e.g., `python:3.9.18-slim-bullseye` with `linux/amd64` platform) for packaging and deploying Zappa applications with native dependencies. Zappa also supports Docker-based deployments directly with the `docker_image_uri` setting.
gotcha Incorrect or insufficient IAM permissions are a common source of deployment failures or runtime errors on AWS Lambda. Zappa requires specific permissions to create and manage Lambda functions, API Gateway, S3 buckets, and other resources.
Fix: Ensure the AWS user/role used by Zappa (`profile_name` in `zappa_settings.json`) has broad administrative access for initial setup or a finely-tuned policy allowing `lambda:*`, `apigateway:*`, `s3:*`, `logs:*`, `iam:PassRole`, `ec2:*`, and `xray:*` if X-Ray is enabled. Set `manage_roles: true` in your `zappa_settings.json` to allow Zappa to attempt to manage roles automatically.

Install

pip install zappa Install Zappa

Quickstart

This quickstart demonstrates how to deploy a simple Flask application to AWS Lambda using Zappa. After creating your Flask app, you initialize Zappa with `zappa init`, which guides you through creating a `zappa_settings.json` file. This file specifies your application's entry point, AWS region, runtime, and other deployment settings. Once configured, you can deploy your application with `zappa deploy <stage_name>` and manage updates or undeployments with corresponding commands. Ensure your AWS credentials are configured (e.g., via `aws configure`).

# 1. Create a Flask app (e.g., app.py)
# pip install Flask
from flask import Flask
import os

app = Flask(__name__)

@app.route('/')
def hello_world():
    return 'Hello from Zappa on Lambda!'

if __name__ == '__main__':
    app.run(debug=True)

# 2. Initialize Zappa in your project directory (where app.py is)
#    Run 'zappa init' and follow the prompts.
#    Example zappa_settings.json will be generated:
#
#    {
#        "dev": {
#            "app_function": "app.app",
#            "aws_region": "us-east-1",
#            "profile_name": "default",
#            "project_name": "my-flask-app",
#            "runtime": "python3.9",
#            "s3_bucket": "zappa-my-flask-app"
#        }
#    }
#
# 3. Deploy your application
# zappa deploy dev
#
# 4. Update your application
# zappa update dev
#
# 5. Undeploy your application
# zappa undeploy dev

view raw JSON →