Django Ledger

A Double Entry Accounting Engine for Django

Django Ledger is a powerful, high-performance financial management and double-entry accounting engine built on top of the Django Web Framework. It provides a robust, developer-friendly API and modular architecture for handling complex accounting tasks in financially driven applications.

Created and developed by Miguel Sanda.

FREE Get Started Guide | Join our Discord | Documentation | QuickStart Notebook

🚀 Key Features

Double-Entry Accounting Engine: Strict balancing and transactional integrity.
Hierarchical Chart of Accounts: Flexible, multi-level account organization.
Financial Statements: Automated Income Statement, Balance Sheet, and Cash Flow Statement generation.
Commercial Documents: Purchase Orders, Sales Orders, Bills, and Invoices.
Financial Ratios & Analytics: Built-in calculation of key financial metrics.
Multi-Tenancy Support: Robust entity and organizational isolation.
Ledgers, Journal Entries & Transactions: Comprehensive general ledger management.
Banking & Imports: OFX & QFX file import capabilities.
Closing Entries & Inventory: Fiscal year-end closing and inventory management with Units of Measure.
Django Admin Integration: Seamless management and built-in Entity Management UI.

📦 Installation & Quick Start

Django Ledger is a Django application. You should have a working Django project before integrating Django Ledger.

1. Add to `INSTALLED_APPS`

Add 'django_ledger' to your project's INSTALLED_APPS in settings.py:

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

2. Configure Context Preprocessor

Add the Django Ledger context preprocessor to your templates configuration:

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

3. Configure URL Routing

Include Django Ledger URLs in your project's root urls.py:

from django.urls import include, path

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

4. Run Database Migrations

Apply database migrations:

python manage.py migrate

5. Run Your Project

python manage.py runserver

Navigate to http://127.0.0.1:8000/ledger and log in using your superuser credentials.

⚙️ Deprecated Behavior Setting (v0.8.0+)

Starting with version v0.8.0, Django Ledger introduces the DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR setting to control access to deprecated features and legacy behaviors.

Default: False (deprecated features are disabled by default).
To temporarily continue using deprecated features during your migration, set DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR = True in your Django settings.

🛠️ Setting Up Django Ledger for Development (Using `uv`)

Django Ledger uses Astral uv for lightning-fast dependency management and virtual environment handling.

Prerequisites

Make sure you have Python (>= 3.11) and uv installed. If you don't have uv installed:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via pip
pip install uv

Development Setup Steps

Clone the repository and navigate into the project directory:

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

Create the virtual environment and sync dependencies:

uv will automatically create a virtual environment and install all dependencies (including development tools) specified in pyproject.toml and locked in uv.lock:

shell uv sync

Activate the virtual environment (optional, or use uv run):

shell source .venv/bin/activate

Apply database migrations:

shell uv run python manage.py migrate (Or simply python manage.py migrate if your virtual environment is activated)

Create a superuser account:

shell uv run python manage.py createsuperuser

Run the development server:

shell uv run python manage.py runserver

Database Dependency Groups

If you prefer using a database backend other than the default SQLite (such as PostgreSQL, MySQL, or MariaDB), uv provides dependency groups that you can sync:

PostgreSQL: shell uv sync --group postgresql Installs psycopg[pool,binary].
MySQL: shell uv sync --group mysql Installs mysqlclient.
MariaDB: shell uv sync --group mariadb Installs mariadb. You can also combine multiple dependency groups when syncing (e.g., uv sync --group dev --group postgresql).

🐳 Setting Up Development Using Docker

If you prefer containerized development: Clone the repository and navigate into it. 1. Ensure '0.0.0.0' is included in ALLOWED_HOSTS in your Django settings. 2. Build and start the containers using Docker Compose: shell docker compose up --build 3. In a separate terminal, create a superuser inside the container: shell docker ps # Find your container ID or name docker exec -it <container_id> python manage.py createsuperuser 4. Open http://127.0.0.1:8000/ledger in your browser.

📜 Licensing & Dual-Licensing Plan

Django Ledger is currently licensed under the GNU General Public License v3.0 (GPL-3.0).

0.9.0 is a transition series: The 0.9.x releases are a transitional series in which Django Ledger prepares to offer dual licensing: GPL-3.0 for open-source use, and a commercial license. Starting with 1.0, Django Ledger will be a dual-licensed project.
Review of existing contributions: To enable this, existing third-party contributions will be reviewed and, where necessary, reimplemented by the project owner, so that the 1.0 release is fully controlled by the project owner or covered by the updated Contributor License Agreement (CLA).
Earlier versions: Previously released versions remain available under GPL-3.0.
New contributions: Contributions accepted from 0.9.0 onward are subject to the updated CLA, which permits dual licensing starting with 1.0.

We sincerely appreciate everyone who has contributed to Django Ledger. See Contribute.md for the full CLA text.

🤝 Getting Involved & Contributing

⚠️ CLA REQUIRED: By submitting a contribution (pull request, patch, documentation, tests, or other material), you agree to the updated Contributor License Agreement in Contribute.md. The CLA permits the project owner to license your contribution under GPL-3.0 and under commercial or proprietary terms. You retain your copyright. Please read it before opening a pull request.

Contributions are welcome. Please read Contribute.md before opening a pull request. The CLA applies to all contributions, including code, tests, documentation, and other project materials. Pull requests should target the dev branch. - Feature Requests & Bug Reports: Open an issue on GitHub. - Questions and implementation help: Contact Miguel Sanda or email [email protected]. - Contribution Guidelines: See Contribute.md.