Registry / aws / apig-wsgi

apig-wsgi

JSON →
library2.20.0pypypi✓ verified 83d ago

apig-wsgi is a Python library that wraps a standard WSGI application in an AWS Lambda handler function, allowing it to be run on AWS API Gateway (REST API or HTTP API) or an Application Load Balancer (ALB). It's currently on version 2.20.0 and sees active maintenance with several releases per year.

pip install apig-wsgi
INSTALL
IMPORT
SIG · APIG-WSGI
A
apig-wsgi
awspythonv2.20.0
Install
1.6s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.20.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

WSGIApplication
from apig_wsgi import WSGIApplication
from apig_wsgi import APIGatewayWSGI
V1Response
from apig_wsgi import V1Response
V2Response
from apig_wsgi import V2Response

This quickstart demonstrates how to create a simple WSGI application and wrap it with `apig-wsgi` for use as an AWS Lambda handler. It includes a basic `lambda_handler` function and a local `if __name__ == '__main__':` block to simulate an API Gateway V1 event and test the integration without deploying to AWS.

import json from apig_wsgi import APIGatewayWSGI, APIGatewayEventType # A simple WSGI application function def my_wsgi_app(environ, start_response): status = '200 OK' headers = [('Content-type', 'application/json')] start_response(status, headers) response_body = { "message": "Hello from WSGI on Lambda!", "path": environ.get('PATH_INFO', '/'), "method": environ.get('REQUEST_METHOD', 'GET'), "query_string": environ.get('QUERY_STRING', '') } return [json.dumps(response_body).encode('utf-8')] # Instantiate the APIGatewayWSGI handler # Use APIGatewayEventType.API_GATEWAY_V1 for REST API (default if omitted) # Use APIGatewayEventType.API_GATEWAY_V2 for HTTP API # Use APIGatewayEventType.ALB for Application Load Balancer apig_wsgi_handler = APIGatewayWSGI(my_wsgi_app, gateway_type=APIGatewayEventType.API_GATEWAY_V1) # This is the standard AWS Lambda handler entry point def lambda_handler(event, context): print(f"Received Lambda event: {json.dumps(event)}") response = apig_wsgi_handler(event, context) print(f"Returning Lambda response: {json.dumps(response)}") return response # Example of how you would test this locally or simulate an event if __name__ == "__main__": # Simulate an API Gateway V1 (REST API) GET event mock_event_v1 = { "resource": "/hello", "path": "/hello", "httpMethod": "GET", "headers": {"Accept": "*/*", "User-Agent": "test-client"}, "queryStringParameters": {"name": "Registry"}, "requestContext": {"resourceId": "xxx", "apiId": "yyy", "resourcePath": "/hello", "httpMethod": "GET", "requestId": "uuid", "identity": {"sourceIp": "127.0.0.1"}, "path": "/hello"}, "body": None, "isBase64Encoded": False } mock_context = {} print("--- Testing API Gateway V1 event ---") lambda_response = lambda_handler(mock_event_v1, mock_context) print("\nSimulated API Gateway V1 Lambda Response:") print(json.dumps(lambda_response, indent=2))
Debug
Known issues
breakingVersion 2.0.0 dropped support for Python versions older than 3.9. Ensure your Lambda runtime environment is configured for Python 3.9 or newer.
fix
Upgrade your Python runtime environment to 3.9+ or pin `apig-wsgi` to `<2.0.0` if you need to use an older Python version (e.g., Python 3.8).
affects: >=2.0.0
breakingIn version 2.0.0, the `APIGatewayWSGI` constructor parameter `aws_event_type` was renamed to `gateway_type`. Additionally, the default `gateway_type` changed from `APIGatewayEventType.ALB` to `APIGatewayEventType.API_GATEWAY_V1`. Existing deployments using ALB without explicitly setting `aws_event_type=ALB` will break.
fix
Update your code to use `gateway_type=` instead of `aws_event_type=`. If you are using an ALB, explicitly set `gateway_type=APIGatewayEventType.ALB`.
affects: >=2.0.0
breakingModule-level constants `TEXT_MIME_TYPES` and `BINARY_MIME_TYPES` were removed in 2.0.0. They were replaced by instance-level parameters `text_response_content_types` and `binary_response_content_types` in the `APIGatewayWSGI` constructor.
fix
Remove references to the old constants. Pass custom content types as `text_response_content_types` or `binary_response_content_types` directly to the `APIGatewayWSGI` constructor.
affects: >=2.0.0
gotchaWhen handling binary responses (e.g., images, PDFs), API Gateway requires the Lambda response to have `isBase64Encoded: true` and the body to be base64-encoded. `apig-wsgi` handles this if the content type is in `binary_response_content_types`, but incorrect configuration can lead to corrupted files or empty responses.
fix
Ensure the `binary_response_content_types` parameter in `APIGatewayWSGI` includes the MIME types for your binary files. Your WSGI application should return raw bytes for these responses.
affects: All
Upgrade
Version history
2.20.0latest on PyPI · released Sep 8, 2025
Audit
Dependencies
aws-lambda-typingrequiredProvides type hints for AWS Lambda event objects and context objects for better development experience.
Agent activity
40 hits · last 30 days
node
35
OpenAI (training)
1
Resources
apig-wsgi — pip install apig-wsgi · libregistry