Django Ledger: double-entry accounting in a Django application

The accounting problem Django Ledger places inside Django

Django Ledger addresses developers who need accounting behavior as part of a larger Django application rather than a separate finance interface connected through generic document APIs. Its central abstraction is double-entry accounting: the feature list names ledgers, journal entries, and transactions, while also exposing a hierarchical chart of accounts. That combination is aimed at software that must represent account structure and accounting movements consistently inside its own domain model.

The scope extends beyond posting transactions. Django Ledger lists an Income Statement, Balance Sheet, Cash Flow, and financial ratio calculations. It also models business documents such as purchase orders, sales orders, bills, and invoices. Inventory management, units of measure, bank account information, OFX and QFX import, and closing entries cover adjacent bookkeeping tasks. Entity management and multi-tenancy support indicate that the project is intended to serve more than one accounting subject, although the README does not provide a detailed tenant-isolation guide.

This makes the project most relevant to Python and Django developers who already understand financial terminology or are working with contributors who do. A team that only wants to upload bank statements or receive a prebuilt general ledger should look elsewhere. Django Ledger begins after the Django project exists: the README explicitly requires working knowledge of Django and a working Django project.

From Django models to financial statements

The visible domain flow starts with entities and ledgers, continues through journal entries and transactions, and produces financial statements and ratios. Accounts are not isolated labels because the chart of accounts is hierarchical. Business documents such as bills and invoices sit alongside the ledger layer, while inventory quantities and units of measure add operational context to financial records.

The README calls this a high-level API and describes Django Ledger as an engine for financially driven applications. It also identifies Django Admin integration and a built-in Entity Management UI. These facts suggest that the application supplies both programmatic accounting objects and browser-facing management components. The README does not describe the internal posting algorithm, concurrency controls, rounding policy, or exact conversion path from every document type to a journal entry. Those details must be checked in the external documentation or the relevant source modules before treating them as settled behavior.

Imports have a narrower documented boundary. OFX and QFX files can be imported, and `ofxtools>=0.9.5` is a direct dependency. The README does not state which institution formats are accepted, how duplicate imports are handled, or whether imported transactions are posted automatically. Account selection and reconciliation behavior should therefore be treated as integration points to verify, not assumed conveniences.

Installing Django Ledger in an existing Django project

The README does not give a `pip install django-ledger` command. For an existing project, it says to add the application, install its context processor, apply migrations, include its URLs, and start Django. The application name in the configuration is exactly `django_ledger`.

Add that application to the existing `INSTALLED_APPS` list. The ellipsis shown by the README is a placeholder in its own example; it should be replaced by the project's current entries rather than copied literally.

INSTALLED_APPS = [
    ...,
    'django_ledger',
    ...,
]

Django Ledger also supplies a template context processor. Add it inside the template engine's existing `OPTIONS` and `context_processors` structure.

TEMPLATES = [
    {
        'OPTIONS': {
            'context_processors': [
                '...',
                'django_ledger.context.django_ledger_context'
            ],
        },
    },
]

The context processor belongs inside the list already used by the project. The repository does not provide a separate settings file for copy-and-paste installation in the documented sequence.

After those changes, apply the database migrations. This is the first step that provisions Django Ledger's database structures in the active database.

python manage.py migrate

Then include `django_ledger.urls` under the `ledger/` prefix in the project's URL configuration.

from django.urls import include, path

urlpatterns = [
    ...,
    path('ledger/', include('django_ledger.urls', namespace='django_ledger')),
    ...,
]

Start the project with the documented Django command. The README says the ledger view will normally appear at `http://127.0.0.1:8000/ledger` when this installation pattern is followed.

python manage.py runserver

Open that address and authenticate with Django superuser credentials. The README documents login as the first real action, but it does not give a complete chart-of-accounts, entity, or first-journal-entry walkthrough on this page.

First development checkout and database entry point

For contributors, the repository documents a separate development setup under `__dev_env__/`. The README warns that this environment is not for production. The checkout uses Git, PipEnv, migrations, and Django's management commands. That route is suitable for examining the project itself; it is not a substitute for the installation steps used by an application that already exists.

Clone the repository and enter its directory.

git clone https://github.com/arrobalytics/django-ledger.git && cd django-ledger

Install PipEnv, create the environment from the repository lock data, and activate it. The README says `pipenv install` is the normal command and also documents selecting a specific interpreter.

pip install -U pipenv
pipenv install
pipenv shell

A project requiring a particular Python executable can use the documented path option instead.

pipenv install --python PATH_TO_INTERPRETER

Apply migrations, create a development superuser, and launch the server. The order matters because migrations prepare the database and the superuser provides a way to reach authenticated features.

python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

The package metadata requires Python `>=3.11` and Django `>=4.2`. The dependency list also includes `django-treebeard`, `faker`, `fpdf2`, `markdown`, `ofxtools`, and `pillow`. These are declared requirements rather than optional integration notes. Exact transitive versions are represented in `requirements.txt` and `uv.lock`, but the README does not document an upgrade or migration procedure for changing a deployed installation.

Multi-tenancy and business-document trade-offs

Multi-tenancy is an explicit feature, but the README offers no implementation detail about isolation, ownership rules, or tenant administration. For a hosted product, that omission matters. A developer needs to know how entities map to application users or organizations and whether every ledger query is constrained by the correct entity before using the feature in production.

The project also groups general ledger records with purchase orders, sales orders, bills, and invoices. That can reduce the number of disconnected models in an accounting-aware application, but it creates a larger integration surface. Product code must decide how document approval, posting, inventory, and payment records relate to ledger transactions. The README lists the document types and closing entries without documenting approval workflows or reversal semantics.

Django Admin integration and the built-in Entity Management UI are useful starting points, yet they are not substitutes for application-specific authorization. The documented first-use path ends at superuser login. It does not explain role design, tenant-aware permissions, audit requirements, or how regular users are separated from administrators.

Financial statement availability also needs qualification. The README confirms Income Statement, Balance Sheet, Cash Flow, and ratio reports. It does not define supported reporting periods, comparative periods, accounting standards, currencies, or export formats. Those are material omissions for regulatory or external reporting decisions.

Docker setup is for the repository development stack

The repository includes `Dockerfile` and `docker-compose.yml`, and the README provides a Docker development workflow. The Compose service builds from the repository `Dockerfile`, maps host port `8000` to container port `8000`, and mounts the project directory at `/app`. That setup gives a contributor a repeatable development process.

Make the entrypoint executable before starting the stack.

sudo chmod +x entrypoint.sh

The README also instructs contributors to add `0.0.0.0` to `ALLOWED_HOSTS` in `settings.py`. Build and run the service with Compose.

docker compose up --build

The service should start from the repository image. The README then directs the contributor to identify the running container and enter it before creating a superuser.

docker ps
docker exec -it containerId /bin/sh

`containerId` is a placeholder that must be replaced with the identifier returned by `docker ps`. Inside the container, create the development administrator.

python manage.py createsuperuser

The README says to open `http://0.0.0.0:8000/` after setup. However, its Compose example mounts the full local directory and builds from `python:latest`. Those choices do not amount to a documented production topology, persistent database service, backup policy, or release-pinned deployment image. The README explicitly describes the development environment as unsuitable for production, so production requirements remain outside this repository guide.

Release changes, license boundaries, and upgrade work

The project is not archived, and the last push was on 2026-10-09. Recent releases include v0.8.5 on 2026-08-24, v0.8.4 on 2026-01-23, and v0.8.3.2 on 2026-01-21. That activity is relevant when evaluating whether the source has recent changes, but release tags alone do not establish upgrade compatibility.

Version v0.8.0 introduced `DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR`. It defaults to `False`, which disables deprecated features and legacy behavior. Projects still depending on those features can temporarily set it to `True`. This is a migration signal rather than a cosmetic warning: enabling the setting preserves legacy behavior, while leaving it at the default removes access to it. The README does not list the affected features or provide a removal schedule.

The `pyproject.toml` declares `GPL-3.0-or-later`, while the repository description lists GPL-3.0. Teams incorporating the package must examine that license and their distribution model separately from technical installation. This article does not provide legal advice or determine compatibility for a particular product.

The documented test command targets the Django application directly.

python manage.py test django_ledger

For an adopter, the first upgrade-specific question is what database migrations ship with the selected release and whether legacy behavior is still enabled. The README does not document a rollback procedure, release-to-release migration checklist, or production upgrade example.

Editorial conclusion

Django Ledger is appropriate for a Django product that needs a domain-specific accounting model, especially when its developers understand bookkeeping and can review migrations, deprecated behavior, and reporting requirements. It is a poor choice for a team seeking a turnkey accounting service, an unexplained installation path, or a deployment model without additional project-specific work. Before adoption, verify Python and Django compatibility, the schema generated by `python manage.py migrate`, behavior of financial statements in the target deployment, and whether every deprecated feature needed during transition can be removed rather than enabled through `DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR`.

Frequently asked questions

Official sources

1. arrobalytics/django-ledger on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases