koalixcrm: a Django CRM and ERP aimed at small businesses

Contacts, documents, projects and accounting in one Django project

koalixcrm is described as an open source Python CRM and ERP based on Django, and the README's own framing is that it is a tiny and easy to use customer relationship management software including tiny and easy to use accounting software.

The feature list in the README covers the whole small business back office. Manage Contacts, Leads and Persons. Manage Products and Prices. Manage Documents such as Invoices, Quotes and Purchase Orders. Manage Projects, Tasks and Work, described as traditional project management. Manage Document Templates. Double Entry Accounting. Create Project Reports. Adjust Access Rights.

The values column on the same page says who it is for. The system is free and open, has a REST interface to many entities, uses the BSD licence, aims for a simple and beautiful user interface and high quality output documents, is aimed at a small business with fewer than ten employees with access, and can be cloud hosted, self hosted, or not hosted at all in a single user offline mode.

That last point is the one that distinguishes it from a hosted CRM. A small consultancy or a sole trader can run the whole thing on a laptop with no network, which is a deployment model almost no hosted product offers, and it is the reason the Docker, self hosted and offline options are listed side by side rather than as alternatives to a cloud tier.

The project is from KoalixSwitzerland, the licence is BSD-3-Clause, and the default branch is develop rather than master, which the README explains in its release process section.

Documents are generated, and XSLT is in the topic list

The xlst tag in the repository topics is not incidental. A CRM whose main output is invoices, quotes and purchase orders is a document generation system, and the feature list mentions both document management and document templates as separate items.

That combination, an entity model on one side and a template system on the other, is what makes the high quality output documents claim plausible. Contacts and products become rows, the template decides the layout, and the accounting side supplies the double entry postings. The template layer is why the system is XSLT based rather than template-string based, and it is also why an organisation with its own document design can keep it: the template is an asset, not a string inside the code.

The REST interface to many entities is the other structural decision. The README lists it as a value rather than a feature, which suggests it is meant to let another system read the data, and the repository root shows the shape of the application: a koalixcrm package, a projectsettings package, a manage.py entry point, a graph.py, an elasticmq.conf for the message queue, and separate directories for microservices, for the message queue commands and for shared utilities, koalixcrm_microservices, koalixcrm_mq_commands and koalixcrm_utils.

Those three extra packages are worth noting. A CRM that has been broken into a core application, a set of microservices and a command layer for the queue is not a single Django project any more, and that shapes both how you deploy it and how you upgrade it.

The stack is orchestrated from a sibling repository

The getting started section is short and points somewhere other than the README. The stack is orchestrated from the sibling repository koalixcrm_system, which holds the docker-compose files and the infrastructure configuration, and the project then offers two guides depending on your environment.

For a workstation, the local setup guide with Docker Desktop covers Windows, macOS and Linux. For a headless Linux host with native Docker, the Linux server install guide covers a VPS or VPC. Both guides cover launching the application and picking the user interface language, with the choices being en-us, de, fr, es and pt-br, selected through the KOALIXCRM_LANGUAGE_CODE environment variable.

Administration and user configuration are covered separately in a configuration guide that the README marks as coming soon, which is worth noting for an evaluation: the two setup guides get you to a running application, but the account and permission configuration is not yet written up in the same place.

Older installations are pointed at a wiki page for installation instructions, hosted under a different organisation name, and the documentation proper lives on readthedocs with a master branch URL, plus a .readthedocs.yaml configuration file at the repository root.

So the deployment shape is a two repository unit. koalixcrm is the application, koalixcrm_system is the infrastructure, and the Docker image is published under the koalixswitzerland organisation with an automated build badge.

A release policy that bans squash merges on main

Most of the README is not about CRM features, it is about how the project is released, and the rules are unusually strict.

The project uses a Git Flow workflow where all development integrates through develop and only stabilised releases are promoted to main. The branch list is spelled out: main is production and every commit on it is a release tagged vX.Y.Z, develop is the integration branch, feature branches are short lived and branch from develop, release branches are short lived stabilisation branches also from develop, and hotfix branches come off main and merge back to both main and develop.

Then there is the rule, and the README explains the reasoning at length. Squash only when merging feature branches into develop, and use real merge commits with --no-ff, never squash, for release into main and for the back merge into develop.

The explanation is a good one and worth repeating because it is the kind of thing teams learn expensively. A squash merge creates a commit that is not a descendant of the source branch's commits, so two long-lived branches lose their shared ancestor and every later release re-lists the entire history, which the README calls a huge diff. Real merges preserve ancestry, so each release diff shows only what is new.

The day to day loop is three commands and a branch name:

git switch develop && git pull
git switch -c feature/QUAQ2-123-short-title
# ...work...
# open PR feature/... -> develop, merge with "Squash and merge"

And the release cut is a longer sequence, with the pull request into main merged with a merge commit, the tag pushed, and then a back merge into develop:

git switch develop && git pull
git switch -c release/2.10.0
# bump version, update changelog, last stabilization fixes only
git push -u origin release/2.10.0

# 1) PR release/2.10.0 -> main, merge with "Create a merge commit" (NEVER squash)
# 2) tag main:
git switch main && git pull
git tag -a v2.10.0 -m "Release 2.10.0"
git push origin v2.10.0
# 3) back-merge so develop gets the version bump / stabilization fixes:
#    PR release/2.10.0 -> develop, merge with "Create a merge commit"

The README also notes that skipping the back-merge is the usual cause of main and develop drifting apart, and that a fix living only on main gets reintroduced as a regression on the next release.

Reading history and the one line that makes it readable

There is a small piece of Git advice in the README that pays for itself immediately, and it is in the reading history section.

git config log.first-parent true     # add --global for all repos
git log --oneline --first-parent main # one line per release, ancestry preserved

With log.first-parent enabled, the log of main shows one line per release rather than every commit that went into it, and the history stays readable precisely because the release process preserved ancestry. The two habits reinforce each other: the merge policy keeps the history clean, and this setting lets you read it.

The section on GitHub repository settings follows, and it asks you to enable both merge styles and use them by convention. That is the practical counterpart of the policy, because the policy is only enforceable if the repository actually allows the merge types the README tells contributors to pick.

Nothing in this section is clever, and that is the point. The README is documenting a set of conventions that are enforced by the branch structure and the pull request merge buttons, and it explains the reason for each one so that a new contributor does not quietly break the history.

Django pinned exactly, versions written by CI, releases from 2024

The packaging tells you how the project is actually released.

The setup.py file resolves the version through a helper with a documented precedence. First the KOALIXCRM_VERSION environment variable, which the CI sets, and second the koalixcrm/version.py file, which is auto-written by CI before the PyPI upload, and which carries a vX.Y.Z-develop fallback during local development. The resolved string is then normalised into PEP 440 form, with a leading v stripped and a -dev suffix rewritten as a .dev suffix, so a git style tag like v1.15.0-dev5 becomes 1.15.0.dev5.

The package is published as koalix-crm, authored by Aaron Riedener, under the BSD licence, and the install requirements are pinned exactly rather than bounded, with Django==5.2.14, django-filebrowser==5.0.0, olefile==0.47 and Pillow==12.3.0 among them. Exact pins in a library that other people install are a maintenance cost, and they are the reason the version of Django in your environment matters.

The tooling around it is modern. The pyproject.toml configures ruff with a line length of 119 following the Django contributing guide, a py311 target, and an exclusion for migrations directories because reformatting auto-generated files causes noisy diffs. There is a pytest.ini, a conftest.py at the root, a tools directory, a .codacy.yml for the Codacy badges, and a readme_claude_code.md, which suggests the project also carries instructions for automated coding assistants.

On the release history, the picture is more mixed. The recent tags are 1.14.0 and 1.13.0, both on 2024-04-07, and before them V0.13 from 2017 with Django 1.3 and Python 2, and 1.13.0 is titled as KoalixCrm V1.13 with Django V3.2, Python3. So the project has already made one major platform jump, from Python 2 and Django 1.3 to Python 3 and Django 3.2, and is now on Django 5.2.

The last push to the repository was on 2026-10-08 and the repository is not archived, so the code is being worked on, but the most recent tagged release in this listing is from April 2024, which is a long gap for a project whose whole value depends on keeping up with supported Django and Python versions.

Editorial conclusion

Adopt koalixcrm if you run a small business, under about ten people with access, that needs contacts, product data, invoices, quotes and basic accounting in one system and wants to run it cloud hosted, self hosted, or offline on a single machine. Do not adopt it if you need a modern, frequently released SaaS CRM, since the last tagged release in the repository is from April 2024 and the project targets small business scale rather than enterprise pipelines. Verify first which Django and Python version your checkout needs, because the setup.py pins Django to an exact version and the release history includes a move from Django 1.3 with Python 2 to Django 3.2 with Python 3, then to the current line, and check that the koalixcrm_system sibling repository is deployed alongside it, since the stack, the Docker Compose files and the infrastructure configuration are not in this repository.

Frequently asked questions

Official sources

1. Issues
2. KoalixSwitzerland/koalixcrm on GitHub
3. License: BSD-3-Clause
4. README
5. Releases