# Horilla HRMS: Installation and Architecture for a Self-Hosted HR Suite

> Horilla HRMS is a Django-based HR suite for organizations managing employee records, recruitment, attendance, leave, payroll, onboarding, and related workflows. The repository supports Docker deployment and source installation, but its Python compatibility, scheduler constraints, and branch strategy require attention.

**horilla/horilla-hr** — Horilla is a free and open source HR software.

- Repository: https://github.com/horilla/horilla-hr
- Website: https://www.horilla.com/
- Stars: 1,496 · Forks: 967
- Language: HTML
- License: LGPL-2.1
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/horilla-horilla-hr

## Horilla's HR workflow coverage

Horilla addresses the problem of collecting core personnel and workforce processes in one self-hosted application. The README identifies employee management, recruitment, onboarding and offboarding, attendance, leave, payroll, performance management, asset management, and an internal helpdesk as core modules. The intended users are organizations that need an HR information system rather than a narrow attendance or leave utility. Employee records form the central area, while the other modules attach operational processes to the workforce. For example, attendance covers biometric integration and automated check-in and check-out, leave management covers policies, approvals, and balances, and recruitment spans job posting through onboarding. Payroll includes salary processing, tax calculations, and compliance features according to the project description. LDAP integration is listed for employee management, which indicates that Horilla can connect identity data with an existing directory rather than requiring every account to be entered only through its own interface. This breadth is useful when HR, managers, recruitment staff, and administrators need related records in the same system. It also creates a substantial application footprint, so the feature list should not be treated as evidence that every module has the same depth or configuration surface.

## Horilla's Django application structure

Based on the repository layout, Horilla is a Django project divided into domain-oriented packages. Directories include employee, recruitment, attendance, leave, payroll, onboarding, offboarding, biometric, helpdesk, horilla_api, horilla_auth, horilla_ldap, and horilla_audit. The project also contains domain-specific support packages for backups, documents, automations, notifications, meetings, themes, and database templates. `manage.py` is the Django management entry point, while `horilla/` contains the project-level application structure. The topic list includes HTMX and jQuery, so the web interface is not limited to a server-rendered static page. However, the repository information does not provide a detailed request flow or a complete map of the API, so those specific mechanisms should not be inferred beyond the visible Django organization. The `horilla_api` and `horilla_auth` packages indicate separate API and authentication areas, while `horilla_audit` indicates audit-related functionality. The presence of `dynamic_fields`, `horilla_widgets`, and `horilla_dbtemplate` suggests reusable form, interface, and database-template concerns. This structure gives operators several domain boundaries to inspect during an evaluation instead of treating the repository as a single undifferentiated HTML application.

## Horilla's Docker services and scheduler boundary

The development Compose file defines a `web` service and a separate `scheduler` service. The web service listens on port 8000 and receives a health check against `http://localhost:8000/health/`. It depends on PostgreSQL and Redis, waits for both to report healthy, and receives development settings such as `DEBUG=1`, `DB_HOST=db`, `DATABASE_URL`, and `REDIS_URL`. The Compose file also mounts the repository at `/app` and provides named volumes for `staticfiles` and `media`. The scheduler runs `python manage.py run_scheduler` in a separate container. Its repository comment gives an important operational constraint: background jobs are not idempotent, so this service should remain at exactly one replica. Scaling the web service is described as safe, while scaling the scheduler can cause repeated payslip processing and repeated backups. This is a concrete deployment boundary rather than a general scaling recommendation. Redis and PostgreSQL are explicit infrastructure dependencies in the development stack, and the scheduler runs independently from web workers. The README also directs production operators to the Docker repository documentation for environment variables, backup volumes, and a working Compose file. The development credentials in `docker-compose.yml` are explicitly weak and marked for local use only, so that file should not be treated as a production security template.

## Installing Horilla with Docker Compose

The README gives Docker Compose as the shortest documented path to a running development instance. The following commands clone the stable `2.0` branch, start the stack, and point a browser at the local port. The first command checks out the default branch, while `docker compose up -d` starts the configured services in the background. The README states that the full migration set runs before the web server binds, so an empty database can take a few minutes.

```bash
git clone https://github.com/horilla/horilla-hr.git
cd horilla-hr

docker compose up -d
open http://localhost:8000
```

The application should eventually be available at `http://localhost:8000`. If the first startup does not appear immediately, the documented migration delay is relevant. The Compose stack also starts PostgreSQL and Redis because the web service declares health dependencies on them. The scheduler runs alongside the web service. This setup is described as development-oriented in `docker-compose.yml`, and the embedded secrets are not suitable for production. The README gives a separate production guide covering Nginx, Apache, and cloud platforms, but it does not provide the complete production commands in this excerpt.

## Installing Horilla from source on Python 3.12 through 3.14

Manual installation is available when an operator wants to run the Django application directly. The README's detailed instructions require Python 3.12, 3.13, or 3.14 and pip 21.3 or newer. It explicitly says that Python 3.15 cannot start the application because `spacy` declares `Requires-Python <3.15` and is imported at module scope. The following sequence creates a virtual environment, upgrades pip before dependency installation, installs `requirements.txt`, creates `.env`, applies migrations, compiles messages, collects static files, and starts Django's development server.

```bash
git clone https://github.com/horilla/horilla-hr.git
cd horilla-hr
python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
cp .env.dist .env
python manage.py migrate
python manage.py compilemessages
python manage.py collectstatic
python manage.py runserver
```

The `.env` file must be edited after copying it. The README warns that upgrading pip first is important because an inherited older pip can miss current manylinux wheel tags and attempt source compilation for packages such as cryptography and PyMuPDF. That can require a C toolchain that is not present on a typical workstation. The requirements file explains why pure-Python packages are pinned exactly while compiled packages use floors and major caps. A deployment should therefore preserve that dependency policy rather than tidying the file into exact pins. The manual path also requires the database and other runtime configuration described in the installation documentation.

## Horilla's Python and quality-gate constraints

Horilla has a notable compatibility boundary that should be checked before an upgrade. The README badge says Python 3.11 or later, while the manual installation section and `requirements.txt` identify supported Python versions as 3.12, 3.13, and 3.14. The more specific runtime instructions should control deployment planning because they explain why Python 3.15 is excluded. `requirements.txt` pins Django within the 5.2.x line and records security-related dependency choices. The repository's `pyproject.toml` configures Ruff for Python 3.12 and deliberately selects a limited set of defect-oriented rules. It records that enabling the complete rule set would expose thousands of findings, including long lines and star-import usage, and says some genuine defect rules are not yet enabled. That choice makes the current gate narrower, not equivalent to a clean full lint result. It also gives maintainers a documented way to expand checks as findings are removed. For adopters, this is relevant mainly to contributors and organizations that intend to modify the code. The documented contribution target is `dev/v2.0`, while `2.0` is the stable deployment branch.

## Horilla's licensing and maintenance boundaries

Horilla is identified as free and open source software under `LGPL-2.1`. The repository contains a `LICENSE` file and the README links to the GNU LGPL v2.1 license text. This article does not interpret the license's obligations or provide legal advice. An organization should review the license and its own distribution, modification, and deployment arrangements separately. Maintenance status should also be described precisely. The repository is not archived, and the last push was on 2026-10-16. Recent releases include 2.1.8 on 2026-09-26, described as a security release, 2.1.7 on 2026-09-15, and 2.1.6 on 2026-09-11. The README distinguishes `2.0`, the stable snapshot used to run or deploy the application, from `dev/v2.0`, the active integration branch for contribution. It also says v1 on `1.0` or `master` is deprioritized and receives case-by-case fixes rather than a guaranteed schedule. Upgrade cost is therefore tied to branch selection, release pinning, migrations, background jobs, and the deployment stack. The Docker guidance recommends pinning an exact image version in production rather than using `latest`, which prevents an unattended deployment from selecting a new release.

## Conclusion

Horilla is suitable for organizations that want a broad, self-hosted HR application and can operate PostgreSQL, Redis, media storage, and a dedicated scheduler. It is a poor fit for teams requiring Python 3.15 support, stateless background processing, or an extensively enforced style gate. Before adoption, verify the Python version, database and backup configuration, scheduler replica count, media storage, and the deployment branch because the project distinguishes stable operation from contribution development.

## FAQ

### What is Horilla HRMS used for?

Horilla HRMS is a self-hosted HR application for employee records, recruitment, onboarding, offboarding, attendance, leave, payroll, performance management, assets, and internal HR support. The README identifies LDAP integration, biometric attendance, payroll processing, and approval-based leave management among its features.

### How do I install and run Horilla locally?

The README documents cloning the repository and running `docker compose up -d`, then opening `http://localhost:8000`. It also documents manual installation with a Python virtual environment, `requirements.txt`, Django migrations, message compilation, static-file collection, and `python manage.py runserver`.

### Which Python versions does Horilla support?

The manual installation instructions and `requirements.txt` list Python 3.12, 3.13, and 3.14. Python 3.15 is explicitly unsupported because `spacy` declares `Requires-Python <3.15` and is imported at module scope.

### Does Horilla need PostgreSQL and Redis for Docker development?

Yes. The development Compose file defines `web` and `scheduler` services, and the web service depends on `db` and `redis` health checks. It supplies `DATABASE_URL` and `REDIS_URL` to the application environment.

### Can the Horilla scheduler run multiple replicas?

The repository configuration says the scheduler should remain at exactly one replica because its jobs are not idempotent. A second copy can produce duplicate payslip runs and duplicate backups, so the scheduler should be scaled separately from the web service.

### Which Horilla branch should I use for deployment and contributions?

The README says `2.0` is the stable branch for running or deploying Horilla and is the default branch checked out by a plain clone. Contributions should branch from and target `dev/v2.0`; the v1 `1.0` and `master` branches are deprioritized.

## Sources

- [horilla/horilla-hr on GitHub](https://github.com/horilla/horilla-hr)
- [License: LGPL-2.1](https://github.com/horilla/horilla-hr/blob/2.0/LICENSE)
- [Project website](https://www.horilla.com/)
- [README](https://github.com/horilla/horilla-hr/blob/2.0/README.md)
- [Releases](https://github.com/horilla/horilla-hr/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/horilla-horilla-hr