The Basics

Last updated Jun 22, 2026

Fetch Handler

As mentioned in the introduction to Python Workers, a Python Worker can be as simple as four lines of code:

from workers import WorkerEntrypoint, Response

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

Similar to other Workers, the main entry point for a Python worker is the fetch handler which handles incoming requests sent to the Worker.

In a Python Worker, this handler is placed in a Default class that extends the WorkerEntrypoint class (which you can import from the workers SDK module).

The Request Interface

The request parameter passed to your fetch handler is a JavaScript Request object, exposed via the foreign function interface (FFI), 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 WorkerEntrypoint, Response
from hello import hello

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        body = await request.json()
        name = body["name"]
        return Response(hello(name))

Many other JavaScript APIs are available in Python Workers via the FFI, so you can call other methods in a similar way.

Once you edit the src/entry.py, Wrangler will automatically restart the local development server.

Now, if you send a POST request with the appropriate body, your Worker will respond with a personalized message.

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

Hello, Python!

Return JSON responses

To return JSON from a Python Worker, use Response.json():

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        data = {"message": "Hello", "status": "ok"}
        return Response.json(data)

The env Attribute

The env attribute on the WorkerEntrypoint 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:

{
    "$schema": "./node_modules/wrangler/config-schema.json",
    "name": "hello-python-worker",
    "main": "src/entry.py",
    "compatibility_flags": [
        "python_workers"
    ],
    // Set this to today's date
    "compatibility_date": "2026-10-27",
    "vars": {
        "API_HOST": "example.com"
    }
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "hello-python-worker"
main = "src/entry.py"
compatibility_flags = [ "python_workers" ]
# Set this to today's date
compatibility_date = "2026-10-27"

[vars]
API_HOST = "example.com"

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

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response(self.env.API_HOST)

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 WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response(hello("World"))

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

Types and Autocompletion

The workers-runtime-sdk package provides the runtime SDK for Python Workers. This package is automatically installed and included in your worker when you use pywrangler, but you can also install it manually to take advantage of type hints and autocompletion in your IDE.

To enable them, add the workers-runtime-sdk package to your pyproject.toml file.

dependencies = [
  "workers-runtime-sdk"
]

Additionally, you can generate types based on your Worker configuration using uv run pywrangler types

This includes Env types based on your bindings, module rules, and runtime types based on the compatibility_date and compatibility_flags in your config file. See

Upgrading pywrangler

To upgrade to the latest version of pywrangler globally, run the following command:

uv tool upgrade workers-py

To upgrade to the latest version of pywrangler in a specific project, run the following command:

uv lock --upgrade-package workers-py

Next Up

• Learn details about local development, deployment, and how Python Workers work.
• Explore the package docs for instructions on how to use packages with Python Workers.
• 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.

Was this helpful?

YesNo

On this page

Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/workers/languages/python/basics/#page","headline":"The Basics","description":"Learn the basics of Python Workers","url":"https://developers.cloudflare.com/workers/languages/python/basics/","inLanguage":"en","image":"https://developers.cloudflare.com/workers/languages/python/basics/og.png?v=34d0ab0db9ff32c9","dateModified":"2026-06-22","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Python code examples demonstrating modules, bindings, and SDK usage in Workers. title: Examples image: https://developers.cloudflare.com/workers/languages/python/examples/og.png?v=e7b4e199277c303d

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/workers/llms.txt
Use this file to discover all available pages before exploring further.