Skip to main content

Wrap a WSGI application in an AWS Lambda handler function for running on API Gateway or an ALB.

Project description

Wrap a WSGI application in an AWS Lambda handler function for running on API Gateway or an ALB.

A quick example:

from apig_wsgi import make_lambda_handler
from myapp.wsgi import app

# Configure this as your entry point in AWS Lambda
lambda_handler = make_lambda_handler(app)


Use pip:

python -m pip install apig-wsgi

Python 3.5 to 3.8 supported.


make_lambda_handler(app, binary_support=False, non_binary_content_type_prefixes=None)

app should be a WSGI app, for example from Django’s or Flask’s Flask() object.

If you want to support sending binary responses, set binary_support to True. ALB’s support binary responses by default, but on API Gateway you need to make sure you have '*/*' in the ‘binary media types’ configuration on your Rest API (whilst API Gateway supports a list of binary media types, using '*/*' is the best way to do it, since it is used to match the request ‘Accept’ header as well, which WSGI applications are likely to ignore).

Note that binary responses aren’t sent if your response has a ‘Content-Type’ starting ‘text/’, ‘application/json’ or ‘application/vnd.api+json’ - this is to support sending larger text responses. To support other content types than the ones specified above, you can set non_binary_content_type_prefixes to a list of content type prefixes of your choice.

If the event from API Gateway contains the requestContext key, for example from custom request authorizers, this will be available in the WSGI environ at the key apig_wsgi.request_context.

If you want to inspect the full event from API Gateway, it’s available in the WSGI environ at the key apig_wsgi.full_event.

If you need the Lambda Context object, it’s available in the WSGI environ at the key apig_wsgi.context.

Multiple values for headers and query parameters are supported. They are enabled automatically on API Gateway but need explict activation on ALB’s.


An example application with Ansible deployment is provided in the example/ directory in the repository. See the README.rst there for guidance.


2.6.0 (2020-03-07)

  • Pass Lambda Context object as a WSGI environ variable (PR #122).

2.5.1 (2020-02-26)

  • Restore setting HTTP_CONTENT_TYPE and HTTP_HOST in the environ, accidentally broken in 2.5.0 with multi-value header feature (Issue #117).

2.5.0 (2020-02-17)

  • Support multi-value headers and query parameters as API Gateway added (Issue #103).
  • Pass full event as a WSGI environ variable (PR #111).

2.4.1 (2020-01-13)

  • Fix URL parameter encoding - URL escaping like %3A will now be passed correctly to your application (Issue #101). Whilst this is a bugfix release, it may break any workarounds you have in your application - please check when upgrading.

2.4.0 (2019-11-15)

  • Converted setuptools metadata to configuration file. This meant removing the __version__ attribute from the package. If you want to inspect the installed version, use importlib.metadata.version("apig-wsgi") (docs / backport).
  • Support Python 3.8.
  • Add application/vnd.api+json to default non-binary content type prefixes.
  • Add support for custom non-binary content type prefixes. This lets you control which content types should be treated as plain text when binary support is enabled.

2.3.0 (2019-08-19)

  • Update Python support to 3.5-3.7, as 3.4 has reached its end of life.
  • Return binary content for gzipped responses with text or JSON content types.

2.2.0 (2019-04-15)

  • If API Gateway event includes requestContext, for example for custom authorizers, pass it in the WSGI environ as apig_wsgi.request_context.

2.1.1 (2019-03-31)

  • Revert adding statusDescription because it turns out API Gateway doesn’t ignore it but instead fails the response with an internal server error.

2.1.0 (2019-03-31)

  • Change statusCode returned to API Gateway / ALB to an integer. It seems API Gateway always supported both strings and integers, whilst ALB only supports integers.
  • Add statusDescription in return value. API Gateway doesn’t seem to use this whilst the ALB documentation mentions it as supported.

2.0.2 (2019-02-07)

  • Drop Python 2 support, only Python 3.4+ is supported now.

2.0.1 (2019-02-07)

  • Temporarily restore Python 2 support. This is in order to fix a packaging metadata issue that 2.0.0 was marked as supporting Python 2, so a new release is needed with a higher version number for python -m pip install apig-wsgi to resolve properly on Python 2. Version 2.0.2+ of apig-wsgi will not support Python 2.

2.0.0 (2019-01-28)

  • Drop Python 2 support, only Python 3.4+ is supported now.
  • If exc_info is passed in, re-raise the exception (previously it would be ignored and crash in a different way). This isn’t the nicest experience, however the behaviour is copied from wsgiref’s simple server, and most WSGI applications implement their own exception conversion to a “500 Internal Server Error” page already.
  • Noted that the EC2 ALB to Lambda integration is also supported as it uses the same event format as API Gateway.

1.2.0 (2018-05-14)

  • Work with base64 encoded body values in requests from API Gateway.

1.1.2 (2018-05-11)

  • Fix crash using binary support for responses missing a Content-Type header.

1.1.1 (2018-05-11)

  • Remove debug print()

1.1.0 (2018-05-10)

  • Add binary_support flag to enable sending binary responses, if enabled on API Gateway.

1.0.0 (2018-03-08)

  • First release on PyPI, working basic integration for WSGI apps on API Gateway.

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 apig-wsgi, version 2.6.0
Filename, size File type Python version Upload date Hashes
Filename, size apig_wsgi-2.6.0-py3-none-any.whl (6.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size apig-wsgi-2.6.0.tar.gz (41.4 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page