Gunicorn: WSGI HTTP Server for UNIX

25.3.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install gunicorn

Common errors

error ModuleNotFoundError: No module named 'gunicorn' ↓

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).

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.

error Failed to find application: 'your_app_module_name' ↓

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.

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.

error [CRITICAL] WORKER TIMEOUT ↓

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.

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.

error OSError: [Errno 98] Address already in use ↓

cause Another process is already listening on the IP address and port that Gunicorn is trying to bind to, preventing Gunicorn from starting.

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).

error Failed at step EXEC spawning /path/to/your/env/bin/gunicorn: No such file or directory ↓

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.

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.

Warnings

breaking Gunicorn 25.3.0 introduces HTTP/2 support (beta) and per-app worker allocation for dirty arbiters, which may affect application performance and compatibility. ↓

fix Review Gunicorn's changelog and documentation for migration guidelines.

gotcha 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. ↓

fix Verify the configuration file's validity and location before starting Gunicorn.

breaking An unspecified error occurred during execution, resulting in an empty error message indicating a non-zero exit status without specific diagnostic details. ↓

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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.19s 20.0M

3.10 slim (glibc) - - 0.17s 21M

3.11 alpine (musl) - - 0.27s 22.3M

3.11 slim (glibc) - - 0.21s 23M

3.12 alpine (musl) - - 0.21s 14.1M

3.12 slim (glibc) - - 0.22s 15M

3.13 alpine (musl) - - 0.20s 13.8M

3.13 slim (glibc) - - 0.18s 14M

3.9 alpine (musl) - - 0.13s 18.5M

3.9 slim (glibc) - - 0.10s 19M

Imports

gunicorn.app.base.BaseApplication
```
from gunicorn.app.base import BaseApplication
```
Correct import path for BaseApplication class

Quickstart stale last tested: 2026-04-23

A minimal example of running a WSGI application with Gunicorn using the BaseApplication class.

import os
from gunicorn.app.base import BaseApplication

class MyApplication(BaseApplication):
    def __init__(self, app, options=None):
        self.options = options or {}
        self.application = app
        super().__init__()

    def load(self):
        return self.application

if __name__ == '__main__':
    app = ...  # Your WSGI application here
    options = {'bind': '0.0.0.0:8000', 'workers': 4}
    MyApplication(app, options).run()