Neolith, for Django: questions and answers

What is Neolith?

Neolith, for Django, is an open source specification and Django library for running a Django app inside a shared process or as its own service, and moving it between the two by configuration, with no change to its code. Its tagline is "Deploy Django apps, not Django projects." Apps talk to each other only through typed contracts, so the same code and tests hold in both arrangements. The specification is independent of Django and Python, and django-neolith is its reference implementation. Neolith is pre-alpha, and nothing is installable yet. It is licensed BSD-3-Clause.

How do I split a Django monolith without rewriting it?

The usual routes are to split it into several Django projects, which duplicates settings, auth wiring and admin and turns imports into hand-written network calls, or to rewrite parts in a lighter framework, which gives up the ORM, migrations and admin.

Neolith's approach is to make the Django app, not the project, the unit of deployment. Each app declares what it provides and needs, apps call each other only through contracts, and each app owns its data. Such an app could then run attached, in a shared process, or detached, as its own service, chosen in configuration. Adoption is designed to go one app at a time.

Neolith is not usable yet. The parts that do not need it can start now: remove foreign keys, joins and transactions between apps, and enforce import boundaries between apps with a tool such as import-linter.

Is Neolith production ready?

No. Neolith is pre-alpha. There are no releases, and nothing is installable yet. The specification is draft 0.1, and nothing in it is stable until django-neolith 0.1 ships against it. Even 0.1 is planned as the smallest version that works end to end, and the only credential between apps that the specification requires so far is a shared-secret token meant for development. Support is planned from Django 5.2 LTS on Python 3.12 up to Django 6.1 on Python 3.15; CI already runs both pairs. Follow the roadmap (opens another site) for progress.

How is Neolith different from splitting into separate Django projects?

Separate Django projects each carry their own settings, auth wiring, admin and boilerplate, and calls between them are hand-written network code. With Neolith, a detached app is meant to stay a Django app, not become a new project: Neolith's app host, the runtime that boots apps, would start it from the app's own declaration of what it provides and needs, so there is no second settings.py, urls.py or manage.py. Callers use the same contract whether the app is attached or detached, so changing the mode is a configuration change. Its data may still have to move, and tooling for that is deferred past 0.1. How the admin works across hosts is an open question. The cost is discipline up front: apps must own their data and talk only through contracts.

How does Neolith compare with django-modulith?

django-modulith is a toolkit for a modular monolith: it scaffolds modules, offers an interface registry for calls between them, and enforces module boundaries with import-linter. The result deploys as one project. Neolith has a different scope: its boundary is a contract that a connector, the object a caller calls through, is designed to carry in-process or over the network, so that an app could also boot and deploy on its own. That part is not built yet. Neolith credits django-modulith with useful groundwork. If you need boundaries inside one deployment today, django-modulith is available now, while Neolith is pre-alpha.

Do detached apps have to talk over HTTP?

No. HTTP with JSON, described by OpenAPI, is the default network transport, and every implementation must support it. The specification allows other transports, such as gRPC or a message queue, as long as they implement the same transport interface and pass the same conformance tests; that part of the design is still proposed. Calling code does not change when the transport does. 0.1 plans only the in-process and HTTP transports, and gRPC is deferred past 0.1.

What do I have to change in my Django apps to use Neolith?

• Declare each app. Each app states the contracts it provides and requires and the resources it needs, on a Neolith app config.
• Call other apps only through contracts. An app may import another app's contract package, never its models, services or signals. A boundary check, neolith check, is planned to enforce this, report-only at first.
• Write contract types as Pydantic models limited to a portable type system.
• Own your data. Each app uses its own database connection. No foreign keys, joins, transactions or migration dependencies across apps. Django's contrib apps count as apps, so a foreign key to auth.User becomes a stored principal ID: an issuer and a subject that identify the user on every host, not the user's database primary key. A GenericForeignKey cannot be relied on across a detach.
• Replace cross-app signals with events. Events are specified only in outline and are deferred past 0.1.
• Accept two costs. Contracts are a versioned API you maintain, and in-process calls pay for serialization so that both modes behave alike; roadmap step 3 is to publish that cost against a direct call.

Adoption is designed to go one app at a time, never as a big-bang migration.

Does Neolith hide network failures, like transparent RPC?

No. Neolith does not pretend a remote call is a local one. Every call can fail, and errors are raised as one ContractError type with a kind, the same in both modes: unavailable when no provider could be reached, timeout when the deadline passes. A timeout leaves the outcome unknown, so Neolith is designed to retry or fall back to another provider only for actions declared idempotent, only on unavailable, and only within the call's deadline.

Does Neolith need Kubernetes, a gateway or a hosted platform?

No. Neolith is a library. It has no gateway, service mesh, broker or orchestrator of its own, and is meant to integrate with the usual ones. Nothing in it depends on a platform the lab operates, and there is no hosted service.

Is Neolith an official Django project?

No. Neolith, for Django, is an independent open source project by Stack314, an engineering lab. It is not affiliated with or endorsed by the Django Software Foundation. It uses the same license as Django, BSD-3-Clause.