Install & Compatibility
Where this runs
tested against v0.31.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 85.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.5s · import 0.000s · 86MB
85MB installed
● package 85MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
NinjaExtraAPI
✓ from ninja_extra import NinjaExtraAPI
✗ from ninja import NinjaAPI
While NinjaExtraAPI inherits from NinjaAPI, directly importing NinjaAPI will miss extra features.
api_controller
✓ from ninja_extra import api_controller
Decorator for defining class-based API controllers.
http_get
✓ from ninja_extra import http_get
HTTP method decorator for controller methods (e.g., @http_get).
ModelControllerBase
✓ from ninja_extra import ModelControllerBase
Base class for generating CRUD operations for Django models.
ModelService
✓ from ninja_extra import ModelService
Base class for defining custom service logic for ModelControllers.
This quickstart demonstrates how to set up a basic API using `NinjaExtraAPI` and define a class-based `APIController` with two simple GET routes. It includes the necessary Django setup for a runnable example. The controller is registered with the main API instance, and its routes are then exposed via Django's URL configuration. Remember to add 'ninja_extra' to your `INSTALLED_APPS`.
import os
from django.conf import settings
from django.urls import path
from ninja_extra import NinjaExtraAPI, api_controller, http_get
if not settings.configured:
settings.configure(
DEBUG=True,
INSTALLED_APPS=[
'django.contrib.auth',
'django.contrib.contenttypes',
'ninja_extra',
],
ROOT_URLCONF=__name__,
SECRET_KEY='a-very-secret-key',
TEMPLATES=[{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'APP_DIRS': True,
}],
)
api = NinjaExtraAPI()
@api_controller("/items", tags=["Items"])
class ItemController:
@http_get("/")
def list_items(self):
return [{"id": 1, "name": "Item 1"}, {"id": 2, "name": "Item 2"}]
@http_get("/{item_id}")
def get_item(self, item_id: int):
return {"id": item_id, "name": f"Item {item_id}"}
api.register_controllers(ItemController)
urlpatterns = [
path("api/", api.urls),
]
# To run this in a Django project, you'd integrate `api.urls` into your project's `urls.py`:
# from django.urls import path, include
# from .api import api # Assuming your api setup is in api.py
# urlpatterns = [
# path("api/", api.urls),
# ]
# Remember to add 'ninja_extra' to your INSTALLED_APPS in settings.py
Debug
Known issues
breakingVersion 0.30.9 introduced a migration from Pydantic v1 config to Pydantic v2 config. This is a significant breaking change if your project relies on Pydantic v1 specific syntax or behaviors.fixReview the Pydantic v2 migration guide (https://pydantic.dev/latest/migration/) and update your schemas and configuration accordingly. Ensure all Pydantic-related code adheres to v2 standards.
affects: >=0.30.9
deprecatedThe `get_api_controller()` method has been deprecated and replaced by the `api_controller` property for accessing controller instances within the API.fixReplace calls to `api.get_api_controller(YourController)` with `api.api_controller[YourController]` or access it directly if already registered. For example, `api.api_controller[ItemController].list_items()`.
affects: >=0.31.2
breakingIn versions prior to 0.22.2, the `service` attribute in `ModelController` was expected to be a class object. It was changed to an instance object, requiring `service_type` to be specified.fixIf defining a custom ModelService for a ModelController, specify it using `service_type = YourCustomModelService` instead of directly assigning to `service`.
affects: <0.22.2 to 0.22.2+
gotchaPrior to versions 0.31.3/0.31.4, there were issues with API-level authentication and throttling not correctly inheriting to controller routes.fixUpgrade to `django-ninja-extra` version 0.31.3 or higher to ensure proper inheritance of API-level authentication and throttling. Manually apply auth/throttle decorators to individual routes as a workaround for older versions.
affects: <0.31.3
gotchaAn MRO (Method Resolution Order) bug might occur with `PaginatedResponseSchema` when using `django-ninja-extra>=0.21` in combination with specific Pydantic versions, causing `TypeError: Cannot create a consistent method resolution order (MRO)`.fixThis issue was largely resolved with the Pydantic v2 migration in 0.30.9. Ensure your `django-ninja-extra` and `pydantic` versions are up-to-date and compatible. If still encountering, try pinning `pydantic` to a compatible v1 version (e.g., `pydantic<2.0,>=1.10`) for older `django-ninja-extra` versions.
affects: >=0.21, <0.30.9
Upgrade
Version history
0.31.4latest on PyPI · released Mar 31, 2026
Audit
Dependencies
djangorequiredCore Django framework requirement.
django-ninjarequiredDjango Ninja Extra is an extension built on top of Django Ninja.
pydanticrequiredUsed by Django Ninja for data validation and serialization.
ninja-schemaoptionalOften used with ModelController for automatic schema generation from Django ORM models.