{"id":435,"library":"gunicorn","title":"Gunicorn: WSGI HTTP Server for UNIX","description":"Gunicorn is a Python WSGI HTTP Server for UNIX, compatible with various web frameworks. Current version: 25.3.0. Released on March 27, 2026. Maintained by volunteers, with a stable release cadence.","status":"active","version":"25.3.0","language":"python","source_language":"en","source_url":"https://github.com/benoitc/gunicorn","tags":["WSGI","HTTP Server","UNIX","Python","Gunicorn"],"install":[{"cmd":"pip install gunicorn","lang":"bash","label":"Install Gunicorn"}],"dependencies":[{"reason":"Provides asynchronous networking support for Gunicorn's worker processes","package":"gevent","optional":true}],"imports":[{"note":"Correct import path for BaseApplication class","symbol":"gunicorn.app.base.BaseApplication","correct":"from gunicorn.app.base import BaseApplication"}],"quickstart":{"code":"import os\nfrom gunicorn.app.base import BaseApplication\n\nclass MyApplication(BaseApplication):\n    def __init__(self, app, options=None):\n        self.options = options or {}\n        self.application = app\n        super().__init__()\n\n    def load(self):\n        return self.application\n\nif __name__ == '__main__':\n    app = ...  # Your WSGI application here\n    options = {'bind': '0.0.0.0:8000', 'workers': 4}\n    MyApplication(app, options).run()","lang":"python","description":"A minimal example of running a WSGI application with Gunicorn using the BaseApplication class."},"warnings":[{"fix":"Review Gunicorn's changelog and documentation for migration guidelines.","message":"Gunicorn 25.3.0 introduces HTTP/2 support (beta) and per-app worker allocation for dirty arbiters, which may affect application performance and compatibility.","severity":"breaking","affected_versions":"25.3.0"},{"fix":"Verify the configuration file's validity and location before starting Gunicorn.","message":"When specifying a configuration file with the '-c' option, ensure the file is a valid Python source file and located in the current working directory or specified path.","severity":"gotcha","affected_versions":"All"},{"fix":"Review the complete log output and system environment for any preceding warnings, notices, or implicit failures. Investigate system-level errors, resource limitations, or unhandled exceptions that might prevent detailed error messages from being printed. Ensure proper permissions and dependency integrity.","message":"An unspecified error occurred during execution, resulting in an empty error message indicating a non-zero exit status without specific diagnostic details.","severity":"breaking","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-05-12T13:48:02.622Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install gunicorn using `pip install gunicorn`. If the error persists for your application module, ensure you are running gunicorn from the correct directory, or explicitly specify the application path, e.g., `gunicorn myproject.wsgi:application` (run from the project root) or `gunicorn --chdir /path/to/project myproject.wsgi:application`.","cause":"Gunicorn is not installed in the active Python environment, or the Python path does not include the directory containing your application's WSGI module (e.g., wsgi.py).","error":"ModuleNotFoundError: No module named 'gunicorn'"},{"fix":"Ensure the WSGI callable in your `wsgi.py` (or equivalent) file is named `application` or `app`. If it has a custom name, explicitly specify it in the gunicorn command, e.g., `gunicorn mymodule:my_custom_app_name`. Verify that `your_app_module_name` correctly points to the Python module containing your WSGI application.","cause":"Gunicorn could not locate the callable WSGI application object (by default named 'application' or 'app') within the specified Python module. This often happens if the variable name is different, the module path is incorrect, or a factory function is used without proper configuration.","error":"Failed to find application: 'your_app_module_name'"},{"fix":"Increase the `--timeout` setting in your gunicorn command (e.g., `gunicorn --timeout 120 ...` for 120 seconds). More importantly, debug and optimize the slow parts of your application code to reduce processing time, or ensure sufficient resources are available for your application.","cause":"A Gunicorn worker process took longer than the configured timeout to respond to a request, leading the master process to kill and restart it. This typically indicates slow application logic, database bottlenecks, or delays from external services.","error":"[CRITICAL] WORKER TIMEOUT"},{"fix":"Stop the process currently occupying the port, or configure Gunicorn to bind to a different available port or IP address (e.g., `gunicorn --bind 0.0.0.0:8001 ...`). You can identify the process using `sudo netstat -tulpn | grep :PORT_NUMBER` (replace `PORT_NUMBER` with the port Gunicorn is trying to use).","cause":"Another process is already listening on the IP address and port that Gunicorn is trying to bind to, preventing Gunicorn from starting.","error":"OSError: [Errno 98] Address already in use"},{"fix":"Verify the absolute path to your `gunicorn` executable within your virtual environment (e.g., by running `which gunicorn` after activating the virtual environment). Update the `ExecStart` directive in your systemd service file (e.g., `/etc/systemd/system/gunicorn.service`) with the correct path, ensuring the virtual environment is properly sourced or the full path to the virtualenv's gunicorn is used.","cause":"This error, commonly seen when running Gunicorn as a systemd service, indicates that the specified path to the `gunicorn` executable in your service file is incorrect, or the virtual environment is not properly activated/configured.","error":"Failed at step EXEC spawning /path/to/your/env/bin/gunicorn: No such file or directory"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":6.8,"disk_size":"20.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":6.8,"disk_size":"21M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.27,"mem_mb":7.6,"disk_size":"22.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.21,"mem_mb":7.6,"disk_size":"23M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.21,"mem_mb":7.2,"disk_size":"14.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.22,"mem_mb":7.2,"disk_size":"15M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":7.1,"disk_size":"13.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":7.1,"disk_size":"14M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":6.2,"disk_size":"18.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":6.2,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}