{"id":4254,"library":"serverless-wsgi","title":"Serverless WSGI","description":"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.","status":"active","version":"3.1.0","language":"en","source_language":"en","source_url":"https://github.com/logandk/serverless-wsgi","tags":["aws","lambda","serverless","wsgi","api gateway","flask","django"],"install":[{"cmd":"pip install serverless-wsgi","lang":"bash","label":"Install Python package"},{"cmd":"npm install serverless-wsgi","lang":"bash","label":"Install Serverless Framework plugin (recommended for deployment)"}],"dependencies":[{"reason":"Core 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.","package":"Werkzeug"}],"imports":[{"note":"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`.","wrong":"from serverless_wsgi import handle_lambda_event","symbol":"handle_request","correct":"import serverless_wsgi\n\ndef lambda_handler(event, context):\n    from your_app_module import app # Your WSGI application instance\n    return serverless_wsgi.handle_request(app, event, context)"}],"quickstart":{"code":"import os\nimport serverless_wsgi\nfrom flask import Flask, jsonify\n\n# Your Flask (or any WSGI) application\napp = Flask(__name__)\n\n@app.route('/')\ndef hello():\n    return jsonify(message='Hello from Serverless WSGI!')\n\n@app.route('/env')\ndef show_env():\n    return jsonify(environment=dict(os.environ))\n\n# The AWS Lambda handler function\ndef lambda_handler(event, context):\n    # This is the core function from the serverless-wsgi Python library\n    # that maps API Gateway events to your WSGI application.\n    return serverless_wsgi.handle_request(app, event, context)\n\n# Example of how you would run it locally (for testing)\nif __name__ == '__main__':\n    # In a real setup, this is handled by `sls wsgi serve` or a WSGI server.\n    # For a minimal local test, you could use Werkzeug's run_simple.\n    from werkzeug.serving import run_simple\n    print(\"Running local Flask app on http://127.0.0.1:5000/\")\n    run_simple('127.0.0.1', 5000, app, use_reloader=True, use_debugger=True)","lang":"python","description":"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`."},"warnings":[{"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).","message":"Version 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.","severity":"breaking","affected_versions":"3.0.0+"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":"2.0.0+"},{"fix":"Replace `werkzeug.urls.url_encode` calls in your application with functions from Python's standard `urllib.parse` module, such as `urllib.parse.urlencode`.","message":"With 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.","severity":"breaking","affected_versions":"3.0.3+"},{"fix":"Update your `serverless.yml` to specify `handler: wsgi_handler.handler` for your Lambda functions.","message":"When 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.","severity":"gotcha","affected_versions":"1.7.0+"},{"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.","message":"Binary 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`).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"AWS 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}