{"id":9478,"library":"apig-wsgi","title":"apig-wsgi","description":"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.","status":"active","version":"2.20.0","language":"en","source_language":"en","source_url":"https://github.com/adamchainz/apig-wsgi","tags":["aws","lambda","api-gateway","alb","wsgi","serverless","python"],"install":[{"cmd":"pip install apig-wsgi","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides type hints for AWS Lambda event objects and context objects for better development experience.","package":"aws-lambda-typing","optional":false}],"imports":[{"note":"The class is directly available at the top level of the package.","wrong":"from apig_wsgi.handler import APIGatewayWSGI","symbol":"APIGatewayWSGI","correct":"from apig_wsgi import APIGatewayWSGI"},{"note":"Enum for specifying the type of API Gateway/ALB event is available at the top level.","wrong":"from apig_wsgi.constants import APIGatewayEventType","symbol":"APIGatewayEventType","correct":"from apig_wsgi import APIGatewayEventType"}],"quickstart":{"code":"import json\nfrom apig_wsgi import APIGatewayWSGI, APIGatewayEventType\n\n# A simple WSGI application function\ndef my_wsgi_app(environ, start_response):\n    status = '200 OK'\n    headers = [('Content-type', 'application/json')]\n    start_response(status, headers)\n    response_body = {\n        \"message\": \"Hello from WSGI on Lambda!\",\n        \"path\": environ.get('PATH_INFO', '/'),\n        \"method\": environ.get('REQUEST_METHOD', 'GET'),\n        \"query_string\": environ.get('QUERY_STRING', '')\n    }\n    return [json.dumps(response_body).encode('utf-8')]\n\n# Instantiate the APIGatewayWSGI handler\n# Use APIGatewayEventType.API_GATEWAY_V1 for REST API (default if omitted)\n# Use APIGatewayEventType.API_GATEWAY_V2 for HTTP API\n# Use APIGatewayEventType.ALB for Application Load Balancer\napig_wsgi_handler = APIGatewayWSGI(my_wsgi_app, gateway_type=APIGatewayEventType.API_GATEWAY_V1)\n\n# This is the standard AWS Lambda handler entry point\ndef lambda_handler(event, context):\n    print(f\"Received Lambda event: {json.dumps(event)}\")\n    response = apig_wsgi_handler(event, context)\n    print(f\"Returning Lambda response: {json.dumps(response)}\")\n    return response\n\n# Example of how you would test this locally or simulate an event\nif __name__ == \"__main__\":\n    # Simulate an API Gateway V1 (REST API) GET event\n    mock_event_v1 = {\n        \"resource\": \"/hello\", \"path\": \"/hello\", \"httpMethod\": \"GET\",\n        \"headers\": {\"Accept\": \"*/*\", \"User-Agent\": \"test-client\"},\n        \"queryStringParameters\": {\"name\": \"Registry\"},\n        \"requestContext\": {\"resourceId\": \"xxx\", \"apiId\": \"yyy\", \"resourcePath\": \"/hello\", \"httpMethod\": \"GET\",\n            \"requestId\": \"uuid\", \"identity\": {\"sourceIp\": \"127.0.0.1\"}, \"path\": \"/hello\"},\n        \"body\": None, \"isBase64Encoded\": False\n    }\n    mock_context = {}\n\n    print(\"--- Testing API Gateway V1 event ---\")\n    lambda_response = lambda_handler(mock_event_v1, mock_context)\n    print(\"\\nSimulated API Gateway V1 Lambda Response:\")\n    print(json.dumps(lambda_response, indent=2))\n","lang":"python","description":"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."},"warnings":[{"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).","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"In 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Module-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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Change `aws_event_type=` to `gateway_type=` in your `APIGatewayWSGI` constructor call. Example: `APIGatewayWSGI(my_wsgi_app, gateway_type=APIGatewayEventType.API_GATEWAY_V1)`","cause":"The `aws_event_type` parameter was renamed to `gateway_type` in `apig-wsgi` version 2.0.0.","error":"TypeError: APIGatewayWSGI.__init__() got an unexpected keyword argument 'aws_event_type'"},{"fix":"The default `gateway_type` changed from ALB to API Gateway V1 in `apig-wsgi` 2.0.0. If you are using an ALB, you must explicitly set `apig_wsgi_handler = APIGatewayWSGI(my_wsgi_app, gateway_type=APIGatewayEventType.ALB)`.","cause":"Often occurs after upgrading `apig-wsgi` to `2.x.x` from an older version when using an ALB, without explicitly setting the `gateway_type`.","error":"Runtime.ExitError: Your function exited with an error. Check the logs for details."},{"fix":"Add `from apig_wsgi import APIGatewayEventType` to your imports.","cause":"The `APIGatewayEventType` enum was used without being imported.","error":"NameError: name 'APIGatewayEventType' is not defined"},{"fix":"Ensure the content type of the binary file is included in the `binary_response_content_types` parameter of `APIGatewayWSGI`. For example: `APIGatewayWSGI(my_wsgi_app, binary_response_content_types={'image/jpeg', 'application/pdf'})`. Your WSGI app must return the raw bytes.","cause":"Binary data is not being correctly base64-encoded and flagged in the API Gateway response.","error":"Image/PDF files downloaded from API Gateway are corrupted or unreadable."}]}