greenlet

3.3.2 verified Tue May 12 auth: no python install: verified quickstart: verified

greenlet is a Python package that provides lightweight in-process concurrent programming through micro-threads called 'greenlets'. The current version is 3.3.2, released on February 20, 2026. The library has a stable release cadence, with updates addressing compatibility and performance improvements.

pip install greenlet

Common errors

error greenlet.error: cannot switch to a different thread ↓

cause This error occurs when an attempt is made to switch execution between greenlets that belong to different operating system threads, which is a fundamental limitation of the greenlet design. Each OS thread maintains its own 'main' greenlet, and greenlets created within one thread cannot be directly switched into from another thread.

fix

Ensure that all greenlet operations, especially calls to greenlet.switch(), occur within the same operating system thread where the greenlet was originally created. If using frameworks like Gevent or Eventlet, ensure that monkey.patch_all() is called at the very beginning of your application's execution, before any other threads are spawned or blocking I/O operations are initiated, to properly 'greenify' the standard library. Avoid passing active greenlet instances directly between Python threads.

error ModuleNotFoundError: No module named 'greenlet._greenlet' ↓

cause This error indicates that the underlying C extension module `_greenlet`, which is a critical component of the `greenlet` library, cannot be found or loaded by Python. This typically points to an incomplete or corrupted installation, an incompatible Python version, or missing C runtime libraries (especially on Windows) that prevent the `.pyd` or `.so` file from being loaded.

fix

First, try reinstalling greenlet with pip install greenlet --no-cache-dir to ensure a fresh download and installation. Ensure your pip and setuptools are up-to-date (python -m pip install --upgrade pip setuptools). If you are on Windows, ensure the appropriate Visual C++ Redistributable packages are installed for your Python version. If issues persist, consider installing greenlet by compiling from source using pip install greenlet --no-binary :all: after confirming that you have the necessary build tools (like a C compiler) installed on your system.

error ERROR: Failed building wheel for greenlet ↓

cause This installation error occurs when `pip` attempts to compile the `greenlet` C extension from source, but the compilation process fails. This is commonly caused by the absence of a C compiler (e.g., GCC on Linux, Xcode Command Line Tools on macOS, or Visual C++ Build Tools on Windows), missing Python development headers, or an incompatibility between the Python version, `setuptools`, and the `greenlet` source code.

fix

Install the required build tools for your operating system: for Debian/Ubuntu, sudo apt-get install build-essential python3-dev; for macOS, install Xcode Command Line Tools (xcode-select --install); for Windows, install Visual C++ Build Tools from Microsoft. Ensure pip and setuptools are updated (python -m pip install --upgrade pip setuptools). If a specific (potentially older) version of greenlet is being requested by another package and causes this error, try to update the dependent package or explicitly install a compatible greenlet version.

Warnings

breaking Support for Python 3.9 was dropped in version 3.3.0. ↓

fix Upgrade your Python environment to version 3.10 or later.

breaking Support for Python 3.7 and 3.8 was removed in version 3.2.0. ↓

fix Upgrade your Python environment to version 3.9 or later.

gotcha Mixing greenlets and signal handlers can lead to hangs if the signal handler switches greenlets without returning. ↓

fix Ensure that signal handlers return control to the main greenlet without switching.

gotcha Using non-reentrant native functions within greenlets can cause subtle issues. ↓

fix Avoid calling non-reentrant native functions from multiple greenlets.

gotcha Greenlets cannot switch between different Python threads. ↓

fix Ensure that greenlet switching occurs within the same thread.

gotcha Garbage collection of greenlets can lead to 'GreenletExit' exceptions if not handled properly. ↓

fix Implement appropriate exception handling to manage 'GreenletExit' during garbage collection.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.00s 23.5M

3.10 slim (glibc) - - 0.00s 21M

3.11 alpine (musl) - - 0.00s 25.4M

3.11 slim (glibc) - - 0.00s 23M

3.12 alpine (musl) - - 0.00s 17.2M

3.12 slim (glibc) - - 0.00s 14M

3.13 alpine (musl) - - 0.00s 16.9M

3.13 slim (glibc) - - 0.00s 14M

3.9 alpine (musl) - - 0.00s 22.1M

3.9 slim (glibc) - - 0.00s 20M

Imports

greenlet
wrong
```
import greenlet
```
correct
```
from greenlet import greenlet
```
Directly importing 'greenlet' does not provide access to the 'greenlet' class; use 'from greenlet import greenlet' instead.
getcurrent
wrong
```
import greenlet
```
correct
```
from greenlet import getcurrent
```
To access the 'getcurrent' function, use 'from greenlet import getcurrent'.

Quickstart verified last tested: 2026-04-23

This example demonstrates creating and switching between two greenlets. 'gr1' starts 'test1', which switches to 'gr2' running 'test2', and then switches back to 'gr1'.

from greenlet import greenlet

def test1():
    print("[gr1] main  -> test1")
    gr2.switch()
    print("[gr1] test1 <- test2")
    return 'test1 done'

def test2():
    print("[gr2] test1 -> test2")
    gr1.switch()

gr1 = greenlet(test1)
gr2 = greenlet(test2)
gr1.switch()