github.com/zappa/Zappa @0.62.1 sqlite

Zappa - Serverless Python

• About
• Installation and Configuration
• Running the Initial Setup / Settings
• Alternative: Generating Settings via CLI
  • Nested JSON Configurations
• Basic Usage
• Initial Deployments
• Updates
  • Docker Workflows
• Rollback
• Scheduling
  • Advanced Scheduling
  • Multiple Expressions
  • Disabled Event
  • EventBridge Rule Naming
• Undeploy
• Package
  • How Zappa Makes Packages
• Template
• Status
• Tailing Logs
• Remote Function Invocation
• Django Management Commands
• SSL Certification
  • Deploying to a Domain With AWS Certificate Manager
  • Deploying to a Domain With a Let's Encrypt Certificate (DNS Auth)
  • Deploying to a Domain With a Let's Encrypt Certificate (HTTP Auth)
  • Deploying to a Domain With Your Own SSL Certs
• Executing in Response to AWS Events
• Asynchronous Task Execution
• Catching Exceptions
• Task Sources
• Direct Invocation
• Remote Invocations
• Restrictions
• Running Tasks in a VPC
• Responses
• Advanced Settings
  • YAML Settings
• Advanced Usage
• Keeping The Server Warm
  • Serving Static Files / Binary Uploads
• Enabling CORS
• Large Projects
• Enabling Bash Completion
• Enabling Secure Endpoints on API Gateway
  • API Key
  • IAM Policy
  • API Gateway Lambda Authorizers
  • Cognito User Pool Authorizer
  • API Gateway Resource Policy
• Setting Environment Variables
  • Local Environment Variables
  • Remote AWS Environment Variables
  • Remote Environment Variables
  • Remote Environment Variables (via an S3 file)
• API Gateway Context Variables
• Catching Unhandled Exceptions
• Using Custom AWS IAM Roles and Policies
  • Custom AWS IAM Roles and Policies for Deployment
  • Custom AWS IAM Roles and Policies for Execution
• AWS X-Ray
• Globally Available Server-less Architectures
• Raising AWS Service Limits
• Dead Letter Queues
• Elastic File System (EFS)
  • Basic Configuration
  • Configuration Options
  • Security Group Configuration
  • Accessing EFS in Your Code
  • Notes
• Unique Package ID
• Application Load Balancer Event Source
• ASGI Support
  • Setting Up a FastAPI App
  • The app_type Setting
  • Starlette Example
  • Quart Example
  • Binary Support with ASGI
  • ASGI Internals
  • ASGI Limitations
• WebSocket Support
  • Using Decorators
  • Using a Base Class
  • Sending Messages to Clients
  • How It Works
• Endpoint Configuration
  • Example Private API Gateway configuration
• Cold Starts (Experimental)
• Lambda Test Console Usage
  • raw_command
  • manage
• Zappa Guides
• Zappa in the Press
• Sites Using Zappa
• Related Projects
• Hacks
• Contributing
  • Using a Local Repo

About

In a hurry? Click to see (now slightly out-dated) slides from Serverless SF!

Zappa makes it super easy to build and deploy server-less, event-driven Python applications (including, but not limited to, WSGI and ASGI web apps) on AWS Lambda + API Gateway. Think of it as "serverless" web hosting for your Python apps. That means infinite scaling, zero downtime, zero maintenance - and at a fraction of the cost of your current deployments!

If you've got a Python web app (including Django, Flask, FastAPI, and Starlette apps), it's as easy as:

$ pip install zappa
$ zappa init
$ zappa deploy

and now you're server-less! Wow!

What do you mean "serverless"?

Okay, so there still is a server - but it only has a 40 millisecond life cycle! Serverless in this case means "without any permanent infrastructure."

With a traditional HTTP server, the server is online 24/7, processing requests one by one as they come in. If the queue of incoming requests grows too large, some requests will time out. With Zappa, each request is given its own virtual HTTP "server" by Amazon API Gateway. AWS handles the horizontal scaling automatically, so no requests ever time out. Each request then calls your application from a memory cache in AWS Lambda and returns the response via Python's WSGI interface. After your app returns, the "server" dies.

Better still, with Zappa you only pay for the milliseconds of server time that you use, so it's many orders of magnitude cheaper than VPS/PaaS hosts like Linode or Heroku - and in most cases, it's completely free. Plus, there's no need to worry about load balancing or keeping servers online ever again.

It's great for deploying serverless microservices with frameworks like Flask and Bottle, and for hosting larger web apps and CMSes with Django. Zappa also supports ASGI frameworks like FastAPI, Starlette, and Quart — deploy async Python apps to Lambda with the same ease. You can use any WSGI or ASGI-compatible app you like! You probably don't need to change your existing applications to use it, and you're not locked into using it.

Zappa also lets you build hybrid event-driven applications that can scale to trillions of events a year with no additional effort on your part! You also get free SSL certificates, global app deployment, API access management, automatic security policy generation, precompiled C-extensions, auto keep-warms, oversized Lambda packages, and many other exclusive features!

And finally, Zappa is super easy to use. You can deploy your application with a single command out of the box!

Awesome!

Installation and Configuration

Before you begin, make sure you are running Python 3.9/3.10/3.11/3.12/3.13/3.14 and you have a valid AWS account and your AWS credentials file is properly installed.

Zappa can easily be installed through pip, like so:

$ pip install zappa

Please note that Zappa must be installed into your project's virtual environment. The virtual environment name should not be the same as the Zappa project name, as this may cause errors.

(If you use pyenv and love to manage virtualenvs with pyenv-virtualenv, you just have to call pyenv local [your_venv_name] and it's ready. Conda users should comment here.)

Next, you'll need to define your local and server-side settings.

Running the Initial Setup / Settings

Zappa can automatically set up your deployment settings for you with the init command:

$ zappa init

This will automatically detect your application type (Flask/Django/FastAPI/Starlette - Pyramid users see here) and help you define your deployment configuration settings. Once you finish initialization, you'll have a file named zappa_settings.json in your project directory defining your basic deployment settings. It will probably look something like this for most WSGI apps:

{
    // The name of your stage
    "dev": {
        // The name of your S3 bucket
        "s3_bucket": "lambda",

        // The modular python path to your WSGI application function.
        // In Flask and Bottle, this is your 'app' object.
        // Flask (your_module.py):
        // app = Flask()
        // Bottle (your_module.py):
        // app = bottle.default_app()
        "app_function": "your_module.app"
    }
}

or for Django:

{
    "dev": { // The name of your stage
       "s3_bucket": "lambda", // The name of your S3 bucket
       "django_settings": "your_project.settings" // The python path to your Django settings.
    }
}

or for ASGI apps (FastAPI, Starlette, Quart):

{
    "dev": {
        "s3_bucket": "lambda",
        "app_function": "your_module.app",
        "app_type": "asgi"
    }
}

See the ASGI Support section for details.

Psst: If you're deploying a Django application with Zappa for the first time, you might want to read Edgar Roman's Django Zappa Guide.

You can define as many stages as your like - we recommend having dev, staging, and production.

Alternative: Generating Settings via CLI

Instead of using the interactive init command, you can also generate your zappa_settings.json programmatically using the settings command with environment variables and command-line arguments:

$ zappa settings --stage dev

This generates a basic settings file with defaults. You can customize it using --config arguments or ZAPPA_ environment variables:

Using command-line arguments

$ zappa settings --stage production \
    --config project_name=myapp \
    --config memory_size=1024 \
    --config timeout_seconds=60

Using environment variables

$ export ZAPPA_PROJECT_NAME=myapp
$ export ZAPPA_MEMORY_SIZE=1024
$ zappa settings --stage production

Command-line arguments override environment variables

$ export ZAPPA_MEMORY_SIZE=512
$ zappa settings --config memory_size=2048  # Uses 2048, not 512

Nested JSON Configurations

The settings command supports complex nested JSON structures for advanced configurations like CORS options, VPC settings, and environment variables:

Configure CORS with nested JSON

$ zappa settings --stage production \
    --config 'cors_options={"allowedOrigins":["*"],"allowedMethods":["GET","POST","PUT"]}'

Configure VPC settings

$ zappa settings --stage production \
    --config 'vpc_config={"SubnetIds":["subnet-123","subnet-456"],"SecurityGroupIds":["sg-789"]}'

Configure environment variables

$ zappa settings --stage production \
    --config 'environment_variables={"DATABASE_URL":"postgres://...","API_KEY":"secret"}'

Configure Lambda layers

```bash $ zappa settings --stage production \ --config 'layers=["arn:aws:l