nanodjango 0.12.1

Run Django models and views from a single file, and convert it to a full project.

nanodjango

• Write a Django site in a single file, using views, models and admin
• Run it locally or in production, or share it as a standalone script
• Automatically convert it to a full Django project when you're ready for it to grow

You may like to watch a lighting talk or read a blog post to get a high level overview of what nanodjango can do.

Quickstart

Install nanodjango:

pip install nanodjango

Write your app in single .py file - for example:

from django.db import models
from nanodjango import Django

app = Django()

@app.admin
class CountLog(models.Model):
    # Standard Django model, registered with the admin site
    timestamp = models.DateTimeField(auto_now_add=True)

@app.route("/")
def count(request):
    # Standard Django function view
    CountLog.objects.create()
    return f"<p>Number of page loads: {CountLog.objects.count()}</p>"

@app.api.get("/add")
def add(request):
    # Django Ninja API support built in
    CountLog.objects.create()
    return {"count": CountLog.objects.count()}

@app.route("/slow/")
async def slow(request):
    import asyncio
    await asyncio.sleep(10)
    return "Async views supported"

Save that as counter.py, then set it up and run it:

nanodjango run counter.py

This will create migrations and a database, and run your project in development mode.

• See Command usage for more options

Convert it to a full site

If your project outgrows its single file, you can convert it into a full Django site:

nanodjango convert counter.py path/to/site --name=counter

• See Converting to a full Django project for more information

Share an app

Nanodjango apps are great for sharing examples and prototypes.

Add inline script metadata at the top with your dependencies:

# /// script
# dependencies = ["nanodjango"]
# ///

and call app.run() at the bottom:

if __name__ == "__main__":
    app.run()

Now your app can be run without installing anything, using uv or pipx:

# Run with uv
uv run ./script.py
# or with pipx
pipx run ./script.py

You can still manually install dependencies and run the script directly with Python:

pip install nanodjango
python script.py

Run management commands

Anything you would normally do with manage.py you can do with nanodjango manage:

nanodjango manage script.py check
nanodjango manage script.py makemigrations script
nanodjango manage script.py runserver 0:8000

Run in production

To run nanodjango with production defaults, use nanodjango serve:

nanodjango serve counter.py

This will use gunicorn, or uvicorn if you have async views. It will also turn off settings.DEBUG, and will not serve media files.

Alternatively, you can pass the app directly to a WSGI or ASGI server if you prefer:

gunicorn -w 4 counter:app
uvicorn counter:app

• See Command usage for more options

Further reading

For more details, see

• Getting started
• Tutorial
• Full Documentation
• Changelog
• Examples