Cloudflare Workers Python SDK

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

Python SDK for building Cloudflare Workers. Allows writing serverless functions in Python that run on the Cloudflare edge network using Pyodide (CPython compiled to WebAssembly). This is distinct from the 'cloudflare' package which is the API client for managing Cloudflare resources.

pip install cloudflare-workers

Common errors

error ModuleNotFoundError: No module named 'fastapi' ↓

cause The Cloudflare Workers Python runtime, powered by Pyodide, supports only pure Python packages or those specifically precompiled for Pyodide. Many common Python packages, including some with C extensions like FastAPI's underlying dependencies (e.g., `httpx`, `numpy`, `boto3`), may not be available or compatible, leading to a ModuleNotFoundError during deployment or runtime.

fix

Verify that all required packages are pure Python and compatible with Pyodide. Consult the Cloudflare Workers documentation for supported Python packages. For unsupported packages, you may need to find pure Python alternatives, implement the functionality manually, or request support for the package. Use pywrangler to manage and bundle your Python dependencies correctly for deployment to Cloudflare Workers.

error ImportError: cannot import name 'wait_until' from 'workers' ↓

cause This error occurs due to a naming mismatch in the `workers` runtime SDK for Python, where the `waitUntil` function is expected but an older or incorrect `asgi` module attempts to import `wait_until`.

fix

Monkey-patch the workers module to alias wait_until to waitUntil before importing asgi or similar modules that expect wait_until. Alternatively, ensure your asgi (or other affected) module and Cloudflare Workers runtime are updated to compatible versions where this naming discrepancy is resolved.

from workers import WorkerEntrypoint, Response
import workers

# Monkey-patch workers to add wait_until alias for waitUntil
workers.wait_until = workers.waitUntil

import asgi # Now this import should work

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        print(asgi)
        return Response("Hello world!")

error ERROR: The name in your Wrangler configuration file (<Worker name>) must match the name of your Worker. ↓

cause When deploying a Cloudflare Worker, the `name` field in your `wrangler.toml` configuration file must exactly match the name of the Worker configured in the Cloudflare dashboard. This ensures consistency between your local project and the deployed Worker.

fix

Update the name field in your wrangler.toml file to precisely match the Worker's name as it appears in the Cloudflare dashboard. For example, if your Worker on the dashboard is named my-python-worker, your wrangler.toml should contain name = "my-python-worker".

name = "my-python-worker"
main = "src/index.py"
compatibility_date = "2024-04-02"

[build]
command = "python -m pywrangler build"

error ERROR: Cannot install mcp because these package versions have conflicting dependencies. ↓

cause This error typically arises during the build or deployment process when `pywrangler` (or `pip` implicitly) tries to resolve dependencies for your Python Worker, and it encounters incompatible versions or limitations imposed by the Pyodide environment. Some packages might have dependencies that are not available or have different versions compatible with Pyodide.

fix

Review your requirements.txt file and the dependencies of the packages you are trying to install. Try to pin specific versions of packages that are known to work with Pyodide/Cloudflare Workers, or identify and remove packages with complex, incompatible dependencies. Consult the pyodide-lock.json if available, or try to simplify your dependencies. If possible, test dependencies in a Pyodide environment locally.

Warnings

breaking The import path is 'cloudflare.workers', NOT 'cloudflare_workers'. The pip package name uses a hyphen but the import namespace uses a dot. ↓

fix from cloudflare.workers import Response

gotcha This package conflicts with the 'cloudflare' PyPI package (the Cloudflare API client). Both occupy the 'cloudflare' namespace. Do not install both in the same environment. ↓

fix Use separate virtual environments if you need both the Workers SDK and the Cloudflare API client.

gotcha Python Workers run on Pyodide (CPython in WebAssembly). Not all Python packages are available. Only pure-Python packages and select packages with Pyodide builds are supported. ↓

fix Check the Pyodide package list for availability. C-extension packages generally won't work unless explicitly ported.

gotcha The handler function must be async. Synchronous handlers will fail silently or raise errors at runtime. ↓

fix Always define your handler as 'async def on_fetch(request, env):' not 'def on_fetch(request, env):'.

gotcha Python Workers require compatibility_flags = ["python_workers"] in wrangler.toml and main must point to a .py file. Without this flag, deployment fails. ↓

fix Add compatibility_flags = ["python_workers"] and set main = "src/entry.py" in wrangler.toml.

deprecated Python Workers support is still in open beta. APIs may change between releases without following semver strictly. ↓

fix Pin your cloudflare-workers version and test thoroughly before upgrading.

breaking The 'cloudflare-workers' package must be installed in your environment for imports like 'from cloudflare.workers import Response' to succeed. Missing the package will result in a ModuleNotFoundError for 'cloudflare'. ↓

fix Add 'cloudflare-workers' to your requirements.txt or install via pip: `pip install cloudflare-workers`

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

Response
wrong
```
from cloudflare_workers import Response
```
correct
```
from cloudflare.workers import Response
```
The import path uses 'cloudflare.workers' with a dot, not an underscore, despite the pip package name being cloudflare-workers.
Request
```
from cloudflare.workers import Request
```
Request object represents the incoming HTTP request to the Worker.
fetch
```
from cloudflare.workers import fetch
```
Use the SDK's fetch function for making outbound HTTP requests from within a Worker.

Quickstart stale last tested: 2026-05-12

Minimal Cloudflare Worker in Python. The on_fetch handler is the entry point for HTTP requests. Deploy with wrangler after configuring wrangler.toml with compatibility_flags = ["python_workers"].

from cloudflare.workers import Response

async def on_fetch(request, env):
    return Response('Hello from Python Workers!')