Cloudflare Workers Python SDK

0.0.8 · active · verified Tue Mar 17

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.

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.

Install

pip install cloudflare-workers Python

Imports

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

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!')

view raw JSON →