Django Ninja

1.6.2 · active · verified Sat Apr 11

Django Ninja is a fast, modern web framework for building APIs with Django using Python type hints, Pydantic, and automatic OpenAPI documentation. It aims for high performance and developer friendliness, similar to FastAPI, while leveraging Django's ecosystem. The library maintains a regular release cadence with frequent updates and bug fixes.

Warnings

breaking Django Ninja v1.0 and later versions require Pydantic V2. Projects upgrading from older Django Ninja versions (0.x) or using Pydantic V1 will encounter breaking changes due to Pydantic's major rewrite.
Fix: Upgrade Pydantic to V2 and refactor Pydantic models according to Pydantic V2 migration guides. Django Ninja's `ModelSchema.Meta` class replaces `BaseModel.Config` for model-based schemas.
gotcha Directly calling Django ORM methods (e.g., `MyModel.objects.all()`) within `async` API views will block the event loop and raise an error. The Django ORM is not fully async-native yet.
Fix: Wrap all blocking (synchronous) ORM calls and other sync I/O operations with `sync_to_async` from `asgiref.sync`. For example: `queryset = await sync_to_async(MyModel.objects.all)()` or `obj = await sync_to_async(MyModel.objects.get)(pk=id)`.
deprecated The previous method of returning a tuple `(status_code, body)` to specify HTTP status codes in responses is deprecated.
Fix: Use the `Status` class explicitly for returning responses with custom HTTP status codes. For example, `return Status(200, {'message': 'Success'})`.
breaking As of v1.6.0, routers became idempotent and reusable. While this is an enhancement, it changes behavior around mounting the same router multiple times. Previous workarounds or reliance on non-idempotent behavior might need review.
Fix: Review any code that mounts the same `Router` instance multiple times to ensure the new idempotent behavior (where decorators, auth, tags, and throttling are fully isolated between mounts) aligns with expectations. This generally resolves previous errors for such patterns.
gotcha Standard Django decorators (e.g., `@cache_page`, `@transaction.atomic`) do not directly integrate with Django Ninja operation functions without explicit wrapping.
Fix: For function-based operations, you might need to manually wrap the Django decorator around the `django-ninja` decorator, or use `router.add_decorator` with a custom universal decorator that handles both sync/async. The `decorate_view` utility or custom middleware might also be necessary for certain scenarios. Refer to the 'Decorators' section of the official documentation.

Install

pip install django-ninja Install stable version

Imports

NinjaAPI
```
from ninja import NinjaAPI
```
Router
```
from ninja import Router
```
ModelSchema
```
from ninja import ModelSchema
```
For `ModelSchema`, `django-ninja` introduced `Meta` for consistency with Django's `ModelForms`. While `Config` is still supported, `Meta` is preferred and more aligned with Pydantic V2's `model_config` concept for custom configurations.
Query
```
from ninja import Query
```
Path
```
from ninja import Path
```
Body
```
from ninja import Body
```
File
```
from ninja import File
```
UploadedFile
```
from ninja.files import UploadedFile
```

Quickstart

This quickstart demonstrates creating a basic API endpoint. Define a `NinjaAPI` instance, then use decorator functions (e.g., `@api.get`) to define API routes. Parameters with type hints are automatically validated and converted. The API instance's `.urls` should be included in your Django project's `urlpatterns`.

from django.contrib import admin
from django.urls import path
from ninja import NinjaAPI

# In your Django project's main urls.py:
# from .api import api # Assuming api.py is next to urls.py
# urlpatterns = [
#     path('admin/', admin.site.urls),
#     path('api/', api.urls) # Mount the NinjaAPI
# ]

# Create an api.py file in your Django project's root directory (next to urls.py)
# api.py
api = NinjaAPI(title="My Awesome API", version="1.0.0")

@api.get("/hello")
def hello(request):
    return "Hello from Django Ninja!"

@api.get("/add")
def add(request, a: int, b: int):
    return {"result": a + b}

view raw JSON →