Skip to content
pymode

Getting Started

Prerequisites

Section titled “Prerequisites”

Quick Start

Section titled “Quick Start”

1. Create a new project

Section titled “1. Create a new project”
Terminal window
npx pymode init my-worker
cd my-worker

This scaffolds:

my-worker/
  pyproject.toml          # Project config
  src/
    entry.py              # Your handler
  .gitignore

2. Write your handler

Section titled “2. Write your handler”
src/entry.py
from pymode.workers import Response


def on_fetch(request, env):
    name = request.query.get("name", ["World"])[0]
    return Response(f"Hello, {name}!")

Note: request.query returns lists (via parse_qs), so use [0] to get the first value.

3. Run locally

Section titled “3. Run locally”
Terminal window
pymode dev

Opens a local dev server at http://localhost:8787. Changes to your Python files are picked up automatically.

4. Deploy

Section titled “4. Deploy”
Terminal window
pymode deploy

Your handler is live on Cloudflare’s edge network within seconds.

Project Structure

Section titled “Project Structure”

A typical PyMode project:

my-worker/
  pyproject.toml          # [tool.pymode] main = "src/entry.py"
  src/
    entry.py              # Entry point with on_fetch()
    routes.py             # Additional modules
    utils.py              # Standard Python imports work
  .dev.vars               # Local environment variables

pyproject.toml

Section titled “pyproject.toml”
[project]
name = "my-worker"
version = "0.1.0"


[tool.pymode]
main = "src/entry.py"
# wizer = true    # Enable deploy-time snapshots (~5ms cold starts)


[tool.pymode.kv_namespaces]
MY_KV = "kv-namespace-id"


[tool.pymode.r2_buckets]
MY_R2 = "r2-bucket-name"


[tool.pymode.d1_databases]
MY_DB = "d1-database-id"

Adding Packages

Section titled “Adding Packages”
Terminal window
# Pure-Python packages
pymode add requests jinja2


# Install from pyproject.toml
pymode install

Packages are bundled into your worker at deploy time.

Examples

Section titled “Examples”

The repo includes working examples you can use as starting points:

ExampleDescription
examples/hello-workerSimple handler with GET routes and query params
examples/api-workerMulti-file project with middleware and routes
examples/workflow-workerDurable workflow with retries and backoff

Next Steps

Section titled “Next Steps”