{"id":8796,"library":"zappa","title":"Zappa","description":"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.","status":"active","version":"0.62.1","language":"en","source_language":"en","source_url":"https://github.com/zappa/Zappa","tags":["aws","lambda","serverless","deployment","wsgi","asgi","flask","django","fastapi"],"install":[{"cmd":"pip install zappa","lang":"bash","label":"Install Zappa"}],"dependencies":[{"reason":"Zappa requires Python 3.9 or newer. The packaging process also depends on the Python environment where Zappa is installed.","package":"python","optional":false},{"reason":"Required for configuring AWS credentials and interacting with AWS services via the CLI, which Zappa leverages for deployment.","package":"awscli","optional":false}],"imports":[],"quickstart":{"code":"# 1. Create a Flask app (e.g., app.py)\n# pip install Flask\nfrom flask import Flask\nimport os\n\napp = Flask(__name__)\n\n@app.route('/')\ndef hello_world():\n    return 'Hello from Zappa on Lambda!'\n\nif __name__ == '__main__':\n    app.run(debug=True)\n\n# 2. Initialize Zappa in your project directory (where app.py is)\n#    Run 'zappa init' and follow the prompts.\n#    Example zappa_settings.json will be generated:\n#\n#    {\n#        \"dev\": {\n#            \"app_function\": \"app.app\",\n#            \"aws_region\": \"us-east-1\",\n#            \"profile_name\": \"default\",\n#            \"project_name\": \"my-flask-app\",\n#            \"runtime\": \"python3.9\",\n#            \"s3_bucket\": \"zappa-my-flask-app\"\n#        }\n#    }\n#\n# 3. Deploy your application\n# zappa deploy dev\n#\n# 4. Update your application\n# zappa update dev\n#\n# 5. Undeploy your application\n# zappa undeploy dev","lang":"python","description":"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`)."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.61.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.61.0"},{"fix":"Rename your virtual environment (e.g., `venv`, `.venv`) so its name does not conflict with your main project directory's name.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"Your Zappa package (including all dependencies) exceeds the AWS Lambda deployment package size limit (250MB unzipped).","error":"Unzipped size must be smaller than 262144000 bytes"},{"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.","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.","error":"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"},{"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.","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.","error":"OSError: Stack creation failed. Please check your CloudFormation console."},{"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.","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.","error":"ImportError: No module named 'your_app_module'"},{"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']`.","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.","error":"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."}]}