Registry / aws / serverless-wsgi

serverless-wsgi

library3.1.0pypypi✓ verified 23d ago

Serverless WSGI is a Python library and Serverless Framework plugin that enables the deployment of standard Python WSGI applications (like Flask, Django, Pyramid) to AWS Lambda, using API Gateway as the HTTP frontend. It transparently converts API Gateway requests to WSGI requests and vice-versa, handling packaging and deployment complexities. The current version is 3.1.0, and it is actively maintained with regular updates.

aws web-framework devops

pip install serverless-wsgi

github ↗package ↗

INSTALL

IMPORT

SIG · SERVERLESS-WSGI

serverless-wsgi

awspythonv3.1.0

Install

1.8s avg

Import

246ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.1.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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.256s · 19.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.236s · 20MB

18MB installed

● package 18MB

Code

Verified usage

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

handle_request

✓ import serverless_wsgi def lambda_handler(event, context): from your_app_module import app # Your WSGI application instance return serverless_wsgi.handle_request(app, event, context)

✗ from serverless_wsgi import handle_lambda_event

When using the serverless-wsgi Python package directly within a Lambda handler, import `serverless_wsgi` and call `serverless_wsgi.handle_request`. The `wsgi_handler.handler` is the entry point configured in `serverless.yml` for the plugin, which internally calls `serverless_wsgi.handle_request`.

This quickstart demonstrates how to integrate `serverless-wsgi` with a simple Flask application for direct use within an AWS Lambda function. The `lambda_handler` function serves as the entry point, passing the AWS event and context to `serverless_wsgi.handle_request`. For actual deployment, the `serverless-wsgi` plugin for the Serverless Framework is typically used, which abstracts away the manual `lambda_handler` setup by configuring `wsgi_handler.handler` in your `serverless.yml`.

import os import serverless_wsgi from flask import Flask, jsonify # Your Flask (or any WSGI) application app = Flask(__name__) @app.route('/') def hello(): return jsonify(message='Hello from Serverless WSGI!') @app.route('/env') def show_env(): return jsonify(environment=dict(os.environ)) # The AWS Lambda handler function def lambda_handler(event, context): # This is the core function from the serverless-wsgi Python library # that maps API Gateway events to your WSGI application. return serverless_wsgi.handle_request(app, event, context) # Example of how you would run it locally (for testing) if __name__ == '__main__': # In a real setup, this is handled by `sls wsgi serve` or a WSGI server. # For a minimal local test, you could use Werkzeug's run_simple. from werkzeug.serving import run_simple print("Running local Flask app on http://127.0.0.1:5000/") run_simple('127.0.0.1', 5000, app, use_reloader=True, use_debugger=True)

serverless --version

Debug

Known issues

breakingVersion 3.0.0 introduced breaking changes for Serverless Framework integration, requiring Serverless Framework versions 2.32.0 or newer. Ensure your `serverless` CLI is updated.

fix

Upgrade your Serverless Framework CLI: `npm install -g serverless` (or `npm install serverless@^2.32.0` if you need to pin to a specific 2.x version).

affects: 3.0.0+

breakingVersion 2.0.0 dropped Python 2 support and requires Werkzeug 2 or later. It also removed deprecated WSGI environment variables (`API_GATEWAY_AUTHORIZER`, `event`, `context`); these should be accessed via `serverless.authorizer`, `serverless.event`, and `serverless.context` respectively.

fix

Ensure your Lambda runtime is Python 3.6+ and that Werkzeug 2.0+ is installed. Update your application code to use the new `serverless.*` variables.

affects: 2.0.0+

breakingWith Werkzeug 3.0.0 (a dependency of `serverless-wsgi`), `werkzeug.urls.url_encode` is no longer available. If your application directly uses this Werkzeug function, you'll need to migrate to `urllib` counterparts.

fix

Replace `werkzeug.urls.url_encode` calls in your application with functions from Python's standard `urllib.parse` module, such as `urllib.parse.urlencode`.

affects: 3.0.3+

gotchaWhen deploying with the Serverless Framework plugin, the handler `wsgi.handler` was renamed to `wsgi_handler.handler` in version 1.7.0. While the old name is still supported, using `wsgi_handler.handler` is the recommended and up-to-date practice.

fix

Update your `serverless.yml` to specify `handler: wsgi_handler.handler` for your Lambda functions.

affects: 1.7.0+

gotchaBinary data (e.g., images, fonts) might be incorrectly base64 encoded by `serverless-wsgi` if the corresponding MIME types are not explicitly added to `binaryMimeTypes` in your API Gateway configuration (typically via `serverless.yml`).

fix

Configure API Gateway to include the necessary `binaryMimeTypes` in your `serverless.yml` to ensure proper decoding of binary responses. You can also extend `serverless_wsgi.TEXT_MIME_TYPES` if you have custom text types that should not be base64 encoded.

affects: All versions

gotchaAWS Lambda has a deployment package size limit (50MB compressed, 250MB uncompressed). Large applications or those with many dependencies might exceed this, especially if development artifacts or unnecessary files are included.

fix

Use a `.serverlessignore` file or the `package.exclude` options in `serverless.yml` to omit large or unnecessary files. Consider using `serverless-python-requirements` with `dockerizePip: true` for complex C-extension dependencies to reduce package size.

affects: All versions

Errors

Common errors & fixes

Unable to import module 'wsgi': No module named 'wsgi'

The `wsgi.py` file, which contains the `handler` function expected by `serverless-wsgi`, is missing from the deployment package or not accessible by the Lambda runtime.

fix

Ensure your `wsgi.py` file is located in the root directory of your project or explicitly included in your `serverless.yml`'s `package.include` configuration.

ModuleNotFoundError: No module named 'some_dependency'

A required Python dependency for your WSGI application was not included in the Lambda deployment package, as `serverless-wsgi` does not automatically bundle `requirements.txt` dependencies.

fix

Install and configure the `serverless-python-requirements` plugin in your `serverless.yml` to automatically bundle dependencies from your `requirements.txt` file. For cross-platform development, ensure `dockerizePip: true` is set.

502 Bad Gateway

Your WSGI application running within the Lambda function encountered an unhandled exception, crashed, or returned an invalid response, leading API Gateway to report a 502.

fix

Check your AWS CloudWatch logs for the Lambda function associated with your `serverless-wsgi` endpoint; the detailed Python traceback will pinpoint the exact cause of the unhandled exception in your application code.

AttributeError: module 'your_module_name' has no attribute 'your_app_callable_name'

The `wsgi.app` configuration in your `serverless.yml` refers to a Python callable (e.g., `app.app`) that does not exist within the specified module or is incorrectly named.

fix

Verify that the `wsgi.app` value in `serverless.yml` accurately maps to the actual WSGI application instance (e.g., `app = Flask(__name__)` as `app.app`) within your Python files, ensuring exact matching of names.

Upgrade

Version history

3.1.0latest on PyPI · released Jun 11, 2025

Audit

Dependencies

WerkzeugrequiredCore WSGI utility library, automatically packaged by serverless-wsgi. Version 2.0+ required since serverless-wsgi v2.0.0; Version 3.0+ impacts url_encode usage.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/logandk/serverless-wsgi ↗

packagehttps://pypi.org/project/serverless-wsgi/ ↗