Python

Cloudflare Workers provides first-class support for Python, including support for:

• The majority of Python's Standard library
• All bindings, including Workers AI, Vectorize, R2, KV, D1, Queues, Durable Objects, Service Bindings and more.
• Environment Variables, and Secrets
• A robust foreign function interface (FFI) that lets you use JavaScript objects and functions directly from Python — including all Runtime APIs
• Built-in packages, including FastAPI ↗, Langchain ↗, httpx ↗ and more.

Python Workers are in beta. Packages do not run in production.

Currently, you can only deploy Python Workers that use the standard library. Packages cannot be deployed and will only work in local development for the time being.

You must add the python_workers compatibility flag to your Worker, while Python Workers are in open beta.

We'd love your feedback. Join the #python-workers channel in the Cloudflare Developers Discord ↗ and let us know what you'd like to see next.

Get started

git clone https://github.com/cloudflare/python-workers-examples
cd python-workers-examples/01-hello
npx wrangler@latest dev

A Python Worker can be as simple as three lines of code:

from workers import Response

def on_fetch(request):
    return Response("Hello World!")

Similar to Workers written in JavaScript, TypeScript, or Rust, the main entry point for a Python worker is the fetch handler. In a Python Worker, this handler is named on_fetch.

To run a Python Worker locally, you use Wrangler, the CLI for Cloudflare Workers:

npx wrangler@latest dev

To deploy a Python Worker to Cloudflare, run wrangler deploy:

npx wrangler@latest deploy

Modules

Python workers can be split across multiple files. Let's create a new Python file, called src/hello.py:

def hello(name):
    return "Hello, " + name + "!"

Now, we can modify src/entry.py to make use of the new module.

from hello import hello
from workers import Response

def on_fetch(request):
    return Response(hello("World"))

Once you edit src/entry.py, Wrangler will automatically detect the change and reload your Worker.

The Request Interface

The request parameter passed to your fetch handler is a JavaScript Request object, exposed via the foreign function interface, allowing you to access it directly from your Python code.

Let's try editing the worker to accept a POST request. We know from the documentation for Request that we can call await request.json() within an async function to parse the request body as JSON. In a Python Worker, you would write:

from workers import Response
from hello import hello

async def on_fetch(request):
    name = (await request.json()).name
    return Response(hello(name))

Once you edit the src/entry.py, Wrangler should automatically restart the local development server. Now, if you send a POST request with the appropriate body, your Worker should respond with a personalized message.

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"name": "Python"}' http://localhost:8787

Hello, Python!

The env Parameter

In addition to the request parameter, the env parameter is also passed to the Python fetch handler and can be used to access environment variables, secrets,and bindings.

For example, let us try setting and using an environment variable in a Python Worker. First, add the environment variable to your Worker's Wrangler configuration file:

wrangler.jsonc

{
  "name": "hello-python-worker",
  "main": "src/entry.py",
  "compatibility_flags": [
    "python_workers"
  ],
  "compatibility_date": "2024-03-20",
  "vars": {
    "API_HOST": "example.com"
  }
}

wrangler.toml

name = "hello-python-worker"
main = "src/entry.py"
compatibility_flags = ["python_workers"]
compatibility_date = "2024-03-20"

[vars]
API_HOST = "example.com"

Then, you can access the API_HOST environment variable via the env parameter:

from workers import Response

async def on_fetch(request, env):
    return Response(env.API_HOST)

Further Reading

• Understand which parts of the Python Standard Library are supported in Python Workers.
• Learn about Python Workers' foreign function interface (FFI), and how to use it to work with bindings and Runtime APIs.
• Explore the Built-in Python packages that the Workers runtime provides.