Install & Compatibility
Where this runs
tested against v26.8.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
py 3.9
✕ build_error
✕ build_error
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
monkey
✓ from gevent import monkey; monkey.patch_all()
✗ import gevent.monkey; gevent.monkey.patch_all()
While `import gevent.monkey` works, `from gevent import monkey` is a common idiom for brevity, especially before calling `patch_all()`.
spawn
✓ import gevent; g = gevent.spawn(my_function, arg1, arg2)
Schedules a function to run as a greenlet.
joinall
✓ import gevent; gevent.joinall([g1, g2])
Waits for multiple greenlets to complete.
sleep
✓ import gevent; gevent.sleep(0)
Cooperatively yields control to other greenlets for a specified duration or immediately if 0.
Greenlet
✓ from gevent import Greenlet
Direct access to the Greenlet class for advanced usage like subclassing.
local
✓ from gevent.local import local
Provides greenlet-local storage, similar to threading.local.
This quickstart demonstrates the core usage of Gevent: first, it applies monkey patching to make standard library functions cooperative. Then, it spawns multiple greenlets to perform I/O-bound tasks (fetching URLs) concurrently, and finally, it waits for all of them to complete.
from gevent import monkey; monkey.patch_all()
import gevent
import requests
def fetch_url(url):
print(f"Fetching {url}...")
try:
response = requests.get(url, timeout=5) # requests uses patched socket
print(f"Finished fetching {url}, status: {response.status_code}")
return len(response.content)
except requests.exceptions.RequestException as e:
print(f"Error fetching {url}: {e}")
return 0
urls = [
"https://www.google.com",
"https://www.github.com",
"https://www.python.org"
]
# Spawn greenlets for each URL fetch
greenlets = [gevent.spawn(fetch_url, url) for url in urls]
# Wait for all greenlets to complete
gevent.joinall(greenlets)
total_bytes = sum(g.value for g in greenlets if g.successful())
print(f"Total bytes fetched: {total_bytes}")
Debug
Known issues
gotchaMonkey patching (`gevent.monkey.patch_all()`) must be performed as early as possible in your application's lifecycle, ideally as the very first lines of code in your main module, on the main thread, and before any other modules that might use blocking I/O are imported. Delaying this can lead to unpredictable behavior, conflicts, or errors because parts of the standard library might already be imported in their unpatched, blocking versions.fixPlace `from gevent import monkey; monkey.patch_all()` at the absolute top of your main script or entry point, even before other imports. If using a framework like Gunicorn with `gevent` workers, check its documentation as it might handle patching for you.
affects: All versions
gotchaUsing Python's `multiprocessing` module in conjunction with `gevent.monkey.patch_all()` (especially if `socket` is patched, which is the default) can be highly problematic and lead to subtle, hard-to-debug issues, as `multiprocessing` relies on standard (unpatched) OS-level threading/socket behavior.fixIf you need multiprocessing with Gevent, consider using `gipc` (gevent-cooperative child processes and IPC), which is designed to integrate safely with Gevent. Alternatively, explicitly disable `socket` patching if `multiprocessing` is used.
affects: All versions
gotchaGevent is designed to make I/O-bound operations (like network requests, disk I/O) concurrent by yielding control during blocking calls. It does not provide true parallelism for CPU-bound tasks within a single process due to Python's Global Interpreter Lock (GIL). Using Gevent for CPU-intensive workloads will not improve performance and can actually make your application slower by adding cooperative multitasking overhead.fixFor CPU-bound tasks, use `multiprocessing` or a task queue system with multiple worker processes. Only apply Gevent where your application's bottleneck is I/O waiting time.
affects: All versions
deprecatedThe magic proxy object `gevent.signal`, which served as both a deprecated alias for `gevent.signal_handler` and the `gevent.signal` module, was removed because it caused confusion for users and static analysis tools.fixUse `gevent.signal_handler` directly when handling signals.
affects: 1.5 and later
breakingIn Gevent v25, changes in import ordering might break projects relying on `gevent.monkey` if `concurrent.futures` is imported before user-defined code. This is because `concurrent.futures` can hold references to unpatched threading threads that cannot be patched by Gevent later.fixEnsure `gevent.monkey.patch_all()` is called at the absolute earliest point in your application, before any other imports, especially those that might implicitly or explicitly import `concurrent.futures` or related threading modules. You may need to restructure imports if this issue arises.
affects: 25.x.x and later
gotchaGevent does not support CPython's experimental free-threading mode (introduced in Python 3.13 and 3.14). If used in such an interpreter, Gevent (and its underlying `greenlet` library) will cause the GIL to be re-enabled. Attempting to use Gevent in free-threading mode is not recommended and may lead to resource leaks.fixAvoid using Gevent with CPython interpreters configured for experimental free-threading mode. Ensure your environment uses a standard CPython build if you rely on Gevent.
affects: CPython 3.13, 3.14+ (when free-threading is enabled)
breakingGevent, like many Python packages with C extensions, requires a C compiler (e.g., gcc) to be present in the environment during installation. Minimal Docker images (e.g., `python:X.Y-slim` or `alpine`) often do not include build tools by default, leading to installation failures.fixEnsure a C compiler and other necessary build tools are installed in your environment before attempting to install gevent. For Debian-based systems (like `python:*-slim`), you can install them using `apt-get update && apt-get install -y build-essential`. For Alpine, use `apk add gcc musl-dev`.
affects: All versions
breakingThe Python 'requests' library is not installed in the environment. This will cause a `ModuleNotFoundError` when the application attempts to import it.fixInstall the 'requests' library using pip: `pip install requests`. Ensure all necessary dependencies are listed in a `requirements.txt` file and installed in the build process.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gevent'
The `gevent` library is not installed in the current Python environment or is not accessible in the `PYTHONPATH`. This can also occur if `gevent` was installed for a different Python version than the one currently in use.
fixInstall `gevent` using pip: `pip install gevent`. Ensure you are in the correct virtual environment if you are using one, and that the Python interpreter running your code is the one for which `gevent` was installed.
gevent.hub.LoopExit: This operation would block forever
This error occurs when a greenlet attempts a synchronous, blocking I/O operation (or a CPU-intensive task) that `gevent` cannot make cooperative, and there are no other active greenlets to switch to, effectively halting the event loop. It can also be caused by greenlets deadlocking on a lock or incorrectly using `gevent` objects with native thread affinity from different threads.
fixIdentify and replace the blocking operation with its `gevent`-cooperative equivalent (e.g., using `gevent.socket` instead of `socket`), offload CPU-bound tasks to a thread pool (`gevent.threadpool`) or a separate process, or ensure that `gevent.monkey.patch_all()` is called at the very beginning of the application to patch standard library blocking calls.
ERROR: Command errored out with exit status 1: command: python setup.py egg_info
This generic error during `gevent` installation, often accompanied by messages about `gcc` or missing headers, indicates a failure to compile `gevent` from source. This typically happens when essential build tools (like `gcc`), Python development headers (`python-devel` or `python3-devel`), or `libevent-dev` are missing from the system. It can also be due to an outdated `setuptools` or `pip` version, or incompatibility with a specific Python or `greenlet` version.
fixInstall the required build dependencies for your operating system (e.g., `sudo apt-get install build-essential python3-dev libevent-dev` on Debian/Ubuntu, or similar for other distros). Upgrade `pip` and `setuptools` to their latest versions (`pip install --upgrade pip setuptools`). Ensure your Python version is compatible with the `gevent` version you are trying to install.
ModuleNotFoundError: No module named 'gevent.wsgi'
The `gevent.wsgi` module has been deprecated and was removed in `gevent` version 1.3.
fixReplace `from gevent.wsgi import WSGIServer` with `from gevent.pywsgi import WSGIServer`. The `gevent.pywsgi` module is the modern replacement for WSGI server functionality.
Monkey patching not being set in subprocesses
This occurs when `gevent.monkey.patch_all()` is not applied in subprocesses or is applied too late in their execution, meaning standard library functions within those subprocesses remain unpatched and blocking. This is particularly problematic in scenarios like `pytest-xdist` or custom multiprocessing setups.
fixEnsure `from gevent import monkey; monkey.patch_all()` is executed as early as possible in the lifecycle of *every* process where cooperative concurrency is desired, including subprocesses. For frameworks like Gunicorn, this is often handled automatically, but for custom subprocesses, you might need to explicitly call it within the subprocess's entry point.
Upgrade
Version history
26.8.0latest on PyPI · released Aug 10, 2026
Audit
Dependencies
greenletrequiredCore dependency for lightweight execution units (greenlets).
cffioptionalInstalled by default on Windows, and will become the default on all platforms in a future release for underlying event loop interactions.
c-aresoptionalUsed for cooperative DNS queries, often bundled with gevent.
libevoptionalOne of the underlying event loop implementations.
libuvoptionalOne of the underlying event loop implementations (default).