How Python Workers Work

Workers written in Python are executed by Pyodide . Pyodide is a CPython (the reference implementation of Python commonly referred to as just "Python") compiled to WebAssembly.

When you write a Python Worker, your code is interpreted directly by Pyodide, within a V8 isolate. Refer to How Workers works to learn more.

A basic Python Worker includes a Python file with a Default class extending WorkerEntrypoint, such as:

from workers import Response, WorkerEntrypoint

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

...and a Wrangler configuration file that points to this .py file:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "hello-world-python-worker",
	"main": "src/entry.py",
	// Set this to today's date
	"compatibility_date": "2026-08-19"
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "hello-world-python-worker"
main = "src/entry.py"
# Set this to today's date
compatibility_date = "2026-08-19"

When you run uv run pywrangler dev to do local dev, the Workers runtime will:

1. Determine which version of Pyodide is required, based on your compatibility date
2. Install any packages necessary based on your pyproject.toml file
3. Create a new v8 isolate for your Worker, and automatically inject Pyodide
4. Serve your Python code using Pyodide

There are no extra toolchain or precompilation steps needed. The Python execution environment is provided directly by the Workers runtime, mirroring how Workers written in JavaScript work.

Refer to the Python examples to learn how to use Python within Workers.

To reduce cold start times, when you deploy a Python Worker, Cloudflare performs as much of the expensive work as possible upfront, at deploy time. When you run uv run pywrangler deploy, the following happens:

1. Wrangler uploads your Python code and any packages included in your pyproject.toml to the Workers API.
2. Cloudflare sends your Python code to the Workers runtime to be validated.
3. Cloudflare creates a new v8 isolate for your Worker, automatically injecting Pyodide.
4. Cloudflare executes the Worker entrypoint module and everything it imports at top level and then take a snapshot of the Workers WebAssembly linear memory. Effectively, we perform the expensive initialization work at deploy time, rather than at runtime.
5. Cloudflare deploys this snapshot alongside your Workers Python code to the Cloudflare network.

When a request comes in to your Worker, we load this snapshot and use it to bootstrap your Worker in an isolate, avoiding expensive initialization time:

Refer to the blog post introducing Python Workers for more detail about performance optimizations and how the Workers runtime will reduce cold starts for Python Workers.

A new version of Python is released every year in August, and a new version of Pyodide is released six (6) months later. When this new version of Pyodide is published, we will add it to Workers by gating it behind a Compatibility Flag, which is only enabled after a specified Compatibility Date. This lets us continually provide updates, without risk of breaking changes, extending the commitment weve made for JavaScript to Python.

Each Python release has a five (5) year support window . Once this support window has passed for a given version of Python, security patches are no longer applied, making this version unsafe to rely on. Following the Workers Runtime policy to never break an application that is live in production, existing Python Workers on versions outside the support window will continue to work. However, we do not recommend using Python versions outside the support window for new projects, and we will not provide patches for issues arising from using these versions. We also cannot guarantee that these older Python versions won't suffer from degraded performance, including higher latency or CPU time usage.