{"id":104,"library":"cloudflare-workers","title":"Cloudflare Workers Python SDK","description":"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.","status":"active","version":"0.0.8","language":"python","source_language":"en","source_url":"https://github.com/cloudflare/cloudflare-workers-sdk","tags":["cloudflare","workers","serverless","edge","python","pyodide","wasm"],"install":[{"cmd":"pip install cloudflare-workers","lang":"bash","label":"Python"}],"dependencies":[{"reason":"Required for local development, testing, and deploying Workers. Installed via npm, not pip.","package":"wrangler","optional":false}],"imports":[{"note":"The import path uses 'cloudflare.workers' with a dot, not an underscore, despite the pip package name being cloudflare-workers.","wrong":"from cloudflare_workers import Response","symbol":"Response","correct":"from cloudflare.workers import Response"},{"note":"Request object represents the incoming HTTP request to the Worker.","symbol":"Request","correct":"from cloudflare.workers import Request"},{"note":"Use the SDK's fetch function for making outbound HTTP requests from within a Worker.","symbol":"fetch","correct":"from cloudflare.workers import fetch"}],"quickstart":{"code":"from cloudflare.workers import Response\n\nasync def on_fetch(request, env):\n    return Response('Hello from Python Workers!')\n","lang":"python","description":"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\"]."},"warnings":[{"fix":"from cloudflare.workers import Response","message":"The import path is 'cloudflare.workers', NOT 'cloudflare_workers'. The pip package name uses a hyphen but the import namespace uses a dot.","severity":"breaking","affected_versions":"all"},{"fix":"Use separate virtual environments if you need both the Workers SDK and the Cloudflare API client.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Check the Pyodide package list for availability. C-extension packages generally won't work unless explicitly ported.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Always define your handler as 'async def on_fetch(request, env):' not 'def on_fetch(request, env):'.","message":"The handler function must be async. Synchronous handlers will fail silently or raise errors at runtime.","severity":"gotcha","affected_versions":"all"},{"fix":"Add compatibility_flags = [\"python_workers\"] and set main = \"src/entry.py\" in wrangler.toml.","message":"Python Workers require compatibility_flags = [\"python_workers\"] in wrangler.toml and main must point to a .py file. Without this flag, deployment fails.","severity":"gotcha","affected_versions":"all"},{"fix":"Pin your cloudflare-workers version and test thoroughly before upgrading.","message":"Python Workers support is still in open beta. APIs may change between releases without following semver strictly.","severity":"deprecated","affected_versions":"all"},{"fix":"Add 'cloudflare-workers' to your requirements.txt or install via pip: `pip install cloudflare-workers`","message":"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'.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T08:07:21.100Z","next_check":"2026-06-17T00:00:00.000Z","problems":[{"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.","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.","error":"ModuleNotFoundError: No module named 'fastapi'"},{"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.\n\n```python\nfrom workers import WorkerEntrypoint, Response\nimport workers\n\n# Monkey-patch workers to add wait_until alias for waitUntil\nworkers.wait_until = workers.waitUntil\n\nimport asgi # Now this import should work\n\nclass Default(WorkerEntrypoint):\n    async def fetch(self, request):\n        print(asgi)\n        return Response(\"Hello world!\")\n```","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`.","error":"ImportError: cannot import name 'wait_until' from 'workers'"},{"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\"`.\n\n```toml\nname = \"my-python-worker\"\nmain = \"src/index.py\"\ncompatibility_date = \"2024-04-02\"\n\n[build]\ncommand = \"python -m pywrangler build\"\n```","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.","error":"ERROR: The name in your Wrangler configuration file (<Worker name>) must match the name of your Worker."},{"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.","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.","error":"ERROR: Cannot install mcp because these package versions have conflicting dependencies."}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}