gunicorn

library26.2.0pypypi✓ verified 24d ago

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.

web-framework http-networking devops

pip install gunicorn

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · GUNICORN

gunicorn

web-frameworkpythonv26.2.0

Install

1.8s avg

Import

190ms

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 v26.2.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.192s · 19.5MB

glibc

py 3.10–3.95 runs

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

18MB installed

● package 18MB

Code

Verified usage

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

gunicorn.app.base.BaseApplication

✓ from gunicorn.app.base import BaseApplication

Correct import path for BaseApplication class

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

gunicorn --version

Debug

Known issues

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

affects: 25.3.0

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

affects: All

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

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'gunicorn'

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

Failed to find application: 'your_app_module_name'

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.

[CRITICAL] WORKER TIMEOUT

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.

OSError: [Errno 98] Address already in use

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

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

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.

Upgrade

Version history

26.2.0latest on PyPI · released Aug 24, 2026

Audit

Dependencies

geventoptionalProvides asynchronous networking support for Gunicorn's worker processes

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/benoitc/gunicorn ↗

packagehttps://pypi.org/project/gunicorn/ ↗

homepagehttps://gunicorn.org ↗

docshttps://gunicorn.org ↗

changeloghttps://gunicorn.org/news/ ↗