zappa

library0.62.1pypypiunverified

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.

aws web-framework devops

pip install zappa

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ZAPPA

zappa

awspythonv0.62.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

zappa --version

Debug

Known issues

breakingZappa 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.

affects: >=0.61.0

gotchaDeployments 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`.

affects: >=0.61.0

gotchaThe 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.

affects: All versions

gotchaDeploying 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.

affects: All versions

gotchaIncorrect 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.

affects: All versions

Errors

Common errors & fixes

Unzipped size must be smaller than 262144000 bytes

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

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.

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'

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.

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']`.

Upgrade

Version history

0.62.1latest on PyPI · released Mar 11, 2026

Audit

Dependencies

pythonrequiredZappa requires Python 3.9 or newer. The packaging process also depends on the Python environment where Zappa is installed.

awsclirequiredRequired for configuring AWS credentials and interacting with AWS services via the CLI, which Zappa leverages for deployment.

Agent activity

46 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/zappa/Zappa ↗

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

homepagehttps://zappa.io ↗