gevent

gevent is a networking and concurrency library for Python that lets you write code in a normal, synchronous style while it runs cooperatively under the hood. Instead of callbacks or explicit async/await, gevent uses greenlets — lightweight, cooperatively-scheduled coroutines — switched by a C-speed event loop (libev on POSIX systems, libuv everywhere including Windows) so thousands of concurrent sockets can be handled without the overhead of OS threads.

Its most distinctive feature is monkey patching: calling gevent.monkey.patch_all() early in a program rewrites the standard library’s blocking primitives (socket, ssl, threading, subprocess, select, time.sleep, and more) so ordinary code — including third-party libraries never written with gevent in mind — becomes cooperative without any rewrite. This has made gevent a long-standing backbone for WSGI servers (gevent.pywsgi), job queues, and any Python service that needs to hold open large numbers of slow connections.

The project has been maintained continuously since 2009, first by Denis Bilenko and, since version 1.1, by Jason Madden with backing from NextThought and Institutional Shareholder Services. Its core primitives (Greenlet, Pool, Queue, Event, Timeout, AsyncResult) deliberately mirror Python’s standard library APIs (threading, queue), so developers already familiar with threaded Python can adopt it with a small learning curve while sidestepping the GIL contention and per-thread memory cost of real OS threads.

What You Get

• Cooperative greenlets — lightweight, stack-switched coroutines scheduled by gevent.spawn/gevent.joinall, far cheaper than OS threads
• A monkey-patching layer (gevent.monkey.patch_all) that makes unmodified standard-library code and third-party packages cooperative automatically
• Cooperative sockets and SSL support for building non-blocking TCP/UDP clients and servers with familiar socket-module semantics
• Built-in WSGI/HTTP server (gevent.pywsgi) and a StreamServer/DatagramServer base for building custom network servers
• A gevent.subprocess module and threadpool (gevent.threadpool) for integrating blocking or CPU-bound work into a cooperative program
• Synchronization primitives that mirror the standard library — Event, Semaphore, Lock, Queue, Timeout — for coordinating greenlets
• Pluggable DNS resolution (threadpool, c-ares, or dnspython) so hostname lookups don’t block the event loop
• An event/plugin system (gevent.events) that fires hooks before and after monkey patching for observability and customization

Common Use Cases

• Running a WSGI application server (via gevent.pywsgi or gunicorn’s gevent worker) that needs to hold open thousands of slow HTTP/WebSocket connections
• Retrofitting an existing synchronous codebase or third-party library with concurrency by monkey-patching instead of rewriting it around async/await
• Building custom TCP/UDP network services — proxies, chat servers, port forwarders — using StreamServer/DatagramServer
• Fan-out I/O-bound work (many parallel HTTP calls, DNS lookups, or DB queries) with a gevent.pool.Pool instead of managing a thread pool by hand
• Running background job workers or task queues that need high connection concurrency without the memory cost of one OS thread per job

Under The Hood

Architecture gevent is layered around a single-threaded event loop hub (gevent.hub.Hub, in src/gevent/hub.py) that wraps a libev or libuv reactor and drives raw greenlet.greenlet objects switched via gevent._greenlet_primitives and gevent._hub_primitives. User-facing Greenlet objects (src/gevent/greenlet.py) wrap the raw greenlet with linking, exception propagation, and result tracking, while low-level waiting is centralized in gevent._waiter.Waiter and gevent.timeout.Timeout so every blocking primitive (Queue, Event, Semaphore, sockets) composes on the same wait/switch mechanism instead of reimplementing it. Cooperative sockets (gevent/socket.py, gevent/_socket3.py) and the WSGI server (gevent/pywsgi.py) sit on top of this hub, and monkey patching (gevent/monkey/__init__.py) works by replacing standard-library module attributes at runtime with these hub-aware equivalents — a design that lets unmodified third-party code become cooperative purely through import-time substitution. What breaks if this abstraction changes: every cooperative primitive in the codebase (sockets, queues, subprocess, threading shims) depends on the same hub/greenlet switching contract, so altering it is a global, not local, change.

Tech Stack The library is written in Python with performance-critical modules also compiled via Cython (.pyx/.pxd files alongside pure-Python fallbacks), and links against the greenlet C extension for stack switching. The event loop backend is vendored/bundled libev and libuv C libraries (see the deps/ directory), with libuv as the default, cross-platform backend and libev as a legacy option; c-ares is vendored for the optional async DNS resolver. The build system is setuptools driven through pyproject.toml and a substantial custom setup.py/_setupares.py/_setuplibev.py, since the package compiles native extensions against these bundled C libraries and against cffi on PyPy. CI runs via GitHub Actions (.github/workflows/ci.yml) and packaging targets manylinux/macOS/Windows wheels for CPython 3.9+ and PyPy 3.9+.

Code Quality The test suite is extensive — over 160 files under src/gevent/tests/, covering sockets, SSL, subprocess, threading interop, monkey-patching edge cases, and known-failure tracking per Python version/platform, run via python -m gevent.tests and orchestrated across many environments in tox.ini (CPython 3.8–3.12, PyPy3, cffi and libuv variants, plus dedicated lint and leak-detection environments). Linting is enforced with a project-specific .pylintrc, and the codebase carries decades of accumulated defensive comments around C-level greenlet/frame access and platform quirks (Windows, PyPy, free-threaded CPython), reflecting a mature project that has had to harden against many real-world edge cases rather than one written from a clean slate.

API Design gevent deliberately mirrors familiar standard-library APIs — Queue, Event, Semaphore, socket and subprocess modules — so a developer who knows threading/socket can be productive with minimal new vocabulary, and the single monkey.patch_all() call is the primary onboarding surface for adopting it in an existing codebase. The public API is extensively documented (91 reStructuredText files under docs/, published to gevent.org and readthedocs), with explicit warnings and tips embedded in docstrings (e.g., patch-order caveats, free-threading limitations) rather than left to be discovered via bug reports.