---
description: Run Django on Python Workers
title: Django
image: https://developers.cloudflare.com/og-docs.png
---

[Skip to content](#main-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.

# Django

Last updated Sep 5, 2026|Copy as Markdown|[View as Markdown](https://developers.cloudflare.com/workers/languages/python/packages/django/index.md)|[Agent setup](https://developers.cloudflare.com/agent-setup/)

[Django ↗](https://www.djangoproject.com/) is supported in Python Workers.

Django applications use protocols called the [Web Server Gateway Interface (WSGI) ↗](https://peps.python.org/pep-3333/)or [Asynchronous Server Gateway Interface (ASGI) ↗](https://asgi.readthedocs.io/en/latest/).

This means that Django never reads from or writes to a socket itself. A WSGI/ASGI application expects to be hooked up to a WSGI/ASGI server, such as [uvicorn ↗](https://uvicorn.dev/). The WSGI/ASGI server handles all of the raw sockets on the application’s behalf.

Python Workers provide adaptors for both WSGI and ASGI, so you can choose any based on whether your Django application deploys to WSGI or ASGI.

## Quick start

To get started with Django in Python Workers, follow these steps:

1. Create a Django project using `pywrangler init`:  
```bash  
uv run pywrangler init django-worker --template https://github.com/cloudflare/python-workers-examples/tree/main/django  
cd django-worker  
```
2. Run your worker locally:  
```bash  
uv run pywrangler dev  
```

## Choose between ASGI and WSGI

Your Django application needs to be served using either ASGI or WSGI. While Python workers is optimized for ASGI, you can still use WSGI which is compatible with Django.

### Serve a WSGI application

Build the application object with `get_wsgi_application()` and pass it to `workers.wsgi.fetch`:

```python
import os

from django.core.wsgi import get_wsgi_application
from workers import wsgi

# your Django settings module
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "app.settings")

app = get_wsgi_application()

Default = wsgi.entrypoint(app)
```

`wsgi.fetch` takes the application object, the incoming request, and the environment. It exposes your bindings to the application through `scope["env"]`.

### Serve an ASGI application

Build the application object with `get_asgi_application()` and pass it to `workers.asgi.fetch`:

```python
import os

from django.core.asgi import get_asgi_application
from workers import asgi

# your Django settings module
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "app.settings")

app = get_asgi_application()

Default = asgi.entrypoint(app)
```

`asgi.fetch` takes the application object, the incoming request, and the environment. It exposes your bindings to the application through `scope["env"]`.

## Configure Django settings

### Pass secrets

If you need a secret (like `SECRET_KEY`) in your Django settings, you can read it from a [Worker secret](https://developers.cloudflare.com/workers/configuration/secrets/):

```python
from workers import env

SECRET_KEY = env.DJANGO_SECRET_KEY
```

Create the secret with `uv run pywrangler secret put DJANGO_SECRET_KEY`.

## Use Cloudflare storage as Django backends

You can use Cloudflare [D1](https://developers.cloudflare.com/d1/) and [Durable Objects](https://developers.cloudflare.com/durable-objects/) as Django database backends. To use them, you need to install the [django-cf ↗](https://github.com/cloudflare/workers-py/tree/main/packages/django-cf) package.

Add `django-cf` to your dependencies:

```toml
[project]
dependencies = [
    "django",
    "django-cf",
]
```

### Database backends

`django-cf` provides two SQLite-compatible backends using Cloudflare's D1 and Durable Objects. Both drive the synchronous Django ORM, so serve your application through the WSGI path when you use them.

Transaction support

The D1 and Durable Object backends do not support transactions.

```python
from django.db import transaction

# This will be a no-op, and rollback will not work
@transaction.atomic
def my_view():
    # ...
```

#### D1 backend

To use D1 as a database backend, first setup your D1 database in Wrangler:

```jsonc
{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-database",
      "database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ]
}
```

```toml
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

Then, configure the backend in your Django settings:

```python
DATABASES = {
    "default": {
        "ENGINE": "django_cf.db.backends.d1",
        # should match the binding name in your wrangler.jsonc
        "CLOUDFLARE_BINDING": "DB",
    }
}
```

You are all set. Your Django application now uses D1 as its database backend.

```python
import os

from django.core.wsgi import get_wsgi_application
from workers import WorkerEntrypoint, wsgi

# your Django settings module
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "app.settings")

application = get_wsgi_application()


class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return await wsgi.fetch(application, request, self.env)
```

#### Durable Objects backend

To use Durable Objects as a database backend, first setup your Durable Objects binding in Wrangler:

```jsonc
{
  "durable_objects": {
    "bindings": [
      {
        "name": "DO_STORAGE",
        "class_name": "DjangoDurableObject"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["DjangoDurableObject"]
    }
  ]
}
```

```toml
[[durable_objects.bindings]]
name = "DO_STORAGE"
class_name = "DjangoDurableObject"

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "DjangoDurableObject" ]
```

Then, configure the backend in your Django settings:

```python
DATABASES = {
    "default": {
        "ENGINE": "django_cf.db.backends.do",
    }
}
```

Then, update your Python worker as follows:

```python
import os

from django.core.wsgi import get_wsgi_application
from django_cf.db.backends.do.storage import set_storage
from workers import WorkerEntrypoint, DurableObject, wsgi

# your Django settings module
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "app.settings")

application = get_wsgi_application()


class DjangoDurableObject(DurableObject):
    def __init__(self, ctx, env):
        super().__init__(ctx, env)

        # Tell Django to use the Durable Object storage
        set_storage(self.ctx.storage.sql)

    async def fetch(self, request):
        return await wsgi.fetch(application, request, self.env)


class Default(WorkerEntrypoint):
    async def fetch(self, request):
        id = self.env.DO_STORAGE.idFromName("my-do-backend")
        stub = self.env.DO_STORAGE.get(id)
        return await stub.fetch(request)
```

## More examples

Clone the `cloudflare/python-workers-examples` repository and run Django examples:

* [django ↗](https://github.com/cloudflare/python-workers-examples/tree/main/django)
* [django with D1 backend ↗](https://github.com/cloudflare/python-workers-examples/tree/main/django-todo-d1)

Was this helpful?

YesNo

## On this page

[![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/)

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/workers/languages/python/packages/django/#page","headline":"Django · Cloudflare Workers docs","description":"Run Django on Python Workers","url":"https://developers.cloudflare.com/workers/languages/python/packages/django/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-05","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/"}}
```