Skip to main content

Amazon AWS API Gateway WSGI wrapper

Project description

npm package

serverless Build Status Coverage Status Dependency Status Dev Dependency Status

A Serverless v1.x plugin to build your deploy Python WSGI applications using Serverless. Compatible WSGI application frameworks include Flask, Django and Pyramid - for a complete list, see:


  • Transparently converts API Gateway and ALB requests to and from standard WSGI requests
  • Supports anything you'd expect from WSGI such as redirects, cookies, file uploads etc.
  • Automatically downloads Python packages that you specify in requirements.txt and deploys them along with your application
  • Convenient wsgi serve command for serving your application locally during development
  • Includes CLI commands for remote execution of Python code (wsgi exec), shell commands (wsgi command) and Django management commands (wsgi manage)


sls plugin install -n serverless-wsgi

This will automatically add the plugin to package.json and the plugins section of serverless.yml.

Flask configuration example

This example assumes that you have intialized your application as app inside

├── requirements.txt
└── serverless.yml

A regular Flask application.

from flask import Flask
app = Flask(__name__)

def cats():
    return "Cats"

def dog(id):
    return "Dog"


Load the plugin and set the configuration in serverless.yml to the module path of your Flask application.

All functions that will use WSGI need to have wsgi_handler.handler set as the Lambda handler and use the default lambda-proxy integration for API Gateway. This configuration example treats API Gateway as a transparent proxy, passing all requests directly to your Flask application, and letting the application handle errors, 404s etc.

Note: The WSGI handler was called wsgi.handler earlier, but was renamed to wsgi_handler.handler in 1.7.0. The old name is still supported but using it will cause a deprecation warning.

service: example

  name: aws
  runtime: python3.6

  - serverless-wsgi

    handler: wsgi_handler.handler
      - http: ANY /
      - http: ANY {proxy+}



Add Flask to the application bundle.



Simply run the serverless deploy command as usual:

$ sls deploy
Serverless: Using Python specified in "runtime": python3.6
Serverless: Packaging Python WSGI handler...
Serverless: Packaging required Python packages...
Serverless: Linking required Python packages...
Serverless: Packaging service...
Serverless: Excluding development dependencies...
Serverless: Unlinking required Python packages...
Serverless: Uploading CloudFormation file to S3...
Serverless: Uploading artifacts...
Serverless: Uploading service .zip file to S3 (864.57 KB)...
Serverless: Validating template...
Serverless: Updating Stack...
Serverless: Checking Stack update progress...
Serverless: Stack update finished...

Other frameworks

Set in serverless.yml according to your WSGI callable:


Automatic requirement packaging

You'll need to include any packages that your application uses in the bundle that's deployed to AWS Lambda. This plugin helps you out by doing this automatically, as long as you specify your required packages in a requirements.txt file in the root of your Serverless service path:


For more information, see

The serverless-wsgi plugin itself depends on werkzeug and will package it automatically, even if werkzeug is not present in your requirements.txt.

You can use the requirement packaging functionality of serverless-wsgi without the WSGI handler itself by including the plugin in your serverless.yml configuration, without specifying the setting. This will omit the WSGI handler from the package, but include any requirements specified in requirements.txt.

If you don't want to use automatic requirement packaging you can set custom.wsgi.packRequirements to false:

    packRequirements: false

In order to pass additional arguments to pip when installing requirements, the pipArgs configuration option is available:

    pipArgs: --no-deps

For a more advanced approach to packaging requirements, consider using When the serverless-python-requirements is added to serverless.yml, the packRequirements option is set to false by default.

If you have packRequirements set to false, or if you use serverless-python-requirements, remember to add werkzeug explicitly in your requirements.txt.

Python version

Python is used for packaging requirements and serving the app when invoking sls wsgi serve. By default, the current runtime setting is expected to be the name of the Python binary in PATH, for instance python3.6. If this is not the name of your Python binary, override it using the pythonBin option:

    pythonBin: python3

Local server

For convenience, a sls wsgi serve command is provided to run your WSGI application locally. This command requires the werkzeug Python package to be installed, and acts as a simple wrapper for starting werkzeug's built-in HTTP server.

By default, the server will start on port 5000.

$ sls wsgi serve
 * Running on http://localhost:5000/ (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!

Configure the port using the -p parameter:

$ sls wsgi serve -p 8000
 * Running on http://localhost:8000/ (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!

When running locally, an environment variable named IS_OFFLINE will be set to True. So, if you want to know when the application is running locally, check os.environ["IS_OFFLINE"].

Remote command execution

The wsgi exec command lets you execute Python code remotely:

$ sls wsgi exec -c "import math; print((1 + math.sqrt(5)) / 2)"

$ cat
for i in range(3):

$ sls wsgi exec -f

The wsgi command command lets you execute shell commands remotely:

$ sls wsgi command -c "pwd"

$ cat
echo "dlrow olleh" | rev

$ sls wsgi command -f
hello world

The wsgi manage command lets you execute Django management commands remotely:

$ sls wsgi manage -c "check --list-tags"

Explicit routes

If you'd like to be explicit about which routes and HTTP methods should pass through to your application, see the following example:

service: example

  name: aws
  runtime: python3.6

  - serverless-wsgi

    handler: wsgi_handler.handler
      - http:
          path: cats
          method: get
          integration: lambda-proxy
      - http:
          path: dogs/{id}
          method: get
          integration: lambda-proxy


Custom domain names

If you use custom domain names with API Gateway, you might have a base path that is at the beginning of your path, such as the stage (/dev, /stage, /prod). In this case, set the API_GATEWAY_BASE_PATH environment variable to let serverless-wsgi know.

The example below uses the serverless-domain-manager plugin to handle custom domains in API Gateway:

service: example

  name: aws
  runtime: python3.6
    API_GATEWAY_BASE_PATH: ${self:custom.customDomain.basePath}

  - serverless-wsgi
  - serverless-domain-manager

    handler: wsgi_handler.handler
      - http: ANY /
      - http: ANY {proxy+}

    basePath: ${opt:stage}
    stage: ${opt:stage}
    createRoute53Record: true

File uploads

In order to accept file uploads from HTML forms, make sure to add multipart/form-data to the list of content types with Binary Support in your API Gateway API. The serverless-apigw-binary Serverless plugin can be used to automate this process.

Keep in mind that, when building Serverless applications, uploading directly to S3 from the browser is usually the preferred approach.

Raw context and event

The raw context and event from AWS Lambda are both accessible through the WSGI request. The following example shows how to access them when using Flask:

from flask import Flask, request
app = Flask(__name__)

def index():

Text MIME types

By default, all MIME types starting with text/ and the following whitelist are sent through API Gateway in plain text. All other MIME types will have their response body base64 encoded (and the isBase64Encoded API Gateway flag set) in order to be delivered by API Gateway as binary data (remember to add any binary MIME types that you're using to the Binary Support list in API Gateway).

This is the default whitelist of plain text MIME types:

  • application/json
  • application/javascript
  • application/xml
  • application/vnd.api+json
  • image/svg+xml

In order to add additional plain text MIME types to this whitelist, use the textMimeTypes configuration option:

      - application/custom+json
      - application/

Preventing cold starts

Common ways to keep lambda functions warm include scheduled events and the WarmUP plugin. Both these event sources are supported by default and will be ignored by serverless-wsgi.

Usage without Serverless

The AWS API Gateway to WSGI mapping module is available on PyPI in the serverless-wsgi package.

Use this package if you need to deploy Python Lambda functions to handle API Gateway events directly, without using the Serverless framework.

pip install serverless-wsgi

Initialize your WSGI application and in your Lambda event handler, call the request mapper:

import app  # Replace with your actual application
import serverless_wsgi

# If you need to send additional content types as text, add then directly
# to the whitelist:
# serverless_wsgi.TEXT_MIME_TYPES.append("application/custom+json")

def handler(event, context):
    return serverless_wsgi.handle_request(, event, context)


Thanks to Zappa, which has been both the inspiration and source of several implementations that went into this project.

Thanks to chalice for the requirement packaging implementation.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for serverless-wsgi, version 1.7.0
Filename, size File type Python version Upload date Hashes
Filename, size serverless_wsgi-1.7.0-py2.py3-none-any.whl (9.2 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size serverless-wsgi-1.7.0.tar.gz (12.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page