Cloudflare Python Workers

Status: Beta (requires python_workers compatibility flag) Runtime: Pyodide (Python 3.12+ compiled to WebAssembly) Package Versions: [email protected], [email protected], [email protected] Last Verified: 2026-01-21

Quick Start (5 Minutes)

1. Prerequisites

Ensure you have installed:

• uv - Python package manager
• Node.js - Required for Wrangler

2. Initialize Project

# Create project directory
mkdir my-python-worker && cd my-python-worker

# Initialize Python project
uv init

# Install pywrangler
uv tool install workers-py

# Initialize Worker configuration
uv run pywrangler init

3. Create Entry Point

Create src/entry.py:

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response("Hello from Python Worker!")

4. Configure wrangler.jsonc

{
  "name": "my-python-worker",
  "main": "src/entry.py",
  "compatibility_date": "2025-12-01",
  "compatibility_flags": ["python_workers"]
}

5. Run Locally

uv run pywrangler dev
# Visit http://localhost:8787

6. Deploy

uv run pywrangler deploy

---

Migration from Pre-December 2025 Workers

If you created a Python Worker before December 2025, you were limited to built-in packages. With pywrangler (Dec 2025), you can now deploy with external packages.

Old Approach (no longer needed):

# Limited to built-in packages only
# Could only use httpx, aiohttp, beautifulsoup4, etc.
# Error: "You cannot yet deploy Python Workers that depend on
# packages defined in requirements.txt [code: 10021]"

New Approach (pywrangler):

# pyproject.toml
[project]
dependencies = ["fastapi", "any-pyodide-compatible-package"]

uv tool install workers-py
uv run pywrangler deploy  # Now works!

Historical Timeline:

• April 2024 - Dec 2025: Package deployment completely blocked
• Dec 8, 2025: Pywrangler released, enabling package deployment
• Jan 2026: Open beta with full package support

See: Package deployment issue history

---

Core Concepts

WorkerEntrypoint Class Pattern

As of August 2025, Python Workers use a class-based pattern (not global handlers):

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        # Access bindings via self.env
        value = await self.env.MY_KV.get("key")

        # Parse request
        url = request.url
        method = request.method

        return Response(f"Method: {method}, URL: {url}")

Accessing Bindings

All Cloudflare bindings are accessed via self.env:

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        # D1 Database
        result = await self.env.DB.prepare("SELECT * FROM users").all()

        # KV Storage
        value = await self.env.MY_KV.get("key")
        await self.env.MY_KV.put("key", "value")

        # R2 Object Storage
        obj = await self.env.MY_BUCKET.get("file.txt")

        # Workers AI
        response = await self.env.AI.run("@cf/meta/llama-2-7b-chat-int8", {
            "prompt": "Hello!"
        })

        return Response("OK")

Supported Bindings:

• D1 (SQL database)
• KV (key-value storage)
• R2 (object storage)
• Workers AI
• Vectorize
• Durable Objects
• Queues
• Analytics Engine

See Cloudflare Bindings Documentation for details.

Request/Response Handling

from workers import WorkerEntrypoint, Response
import json

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        # Parse JSON body
        if request.method == "POST":
            body = await request.json()
            return Response(
                json.dumps({"received": body}),
                headers={"Content-Type": "application/json"}
            )

        # Query parameters
        url = URL(request.url)
        name = url.searchParams.get("name", "World")

        return Response(f"Hello, {name}!")

Scheduled Handlers (Cron)

from workers import handler

@handler
async def on_scheduled(event, env, ctx):
    # Run on cron schedule
    print(f"Cron triggered at {event.scheduledTime}")

    # Do work...
    await env.MY_KV.put("last_run", str(event.scheduledTime))

Configure in wrangler.jsonc:

{
  "triggers": {
    "crons": ["*/5 * * * *"]  // Every 5 minutes
  }
}

---

Python Workflows

Python Workflows enable durable, multi-step automation with automatic retries and state persistence.

Why Decorator Pattern?

Python Workflows use the @step.do() decorator pattern because Python does not easily support anonymous callbacks (unlike JavaScript/TypeScript which allows inline arrow functions). This is a fundamental language difference, not a limitation of Cloudflare's implementation.

JavaScript Pattern (doesn't translate):

await step.do("my step", async () => {
  // Inline callback
  return result;
});

Python Pattern (required):

@step.do("my step")
async def my_step():
    # Named function with decorator
    return result

result = await my_step()

Source: Python Workflows Blog

Concurrency with asyncio.gather

Pyodide captures JavaScript promises (thenables) and proxies them as Python awaitables. This enables Promise.all-equivalent behavior using standard Python async patterns:

import asyncio

@step.do("step_a")
async def step_a():
    return "A"

@step.do("step_b")
async def step_b():
    return "B"

# Concurrent execution (like Promise.all)
results = await asyncio.gather(step_a(), step_b(