EspoCRM: a PHP CRM you host and extend yourself

What EspoCRM replaces, and for whom

EspoCRM is a customer relationship management application that stores leads, contacts, sales opportunities, marketing campaigns and support cases in one place. The README frames the goal as keeping all business information in a single interface, and the topic list on the repository adds the surrounding scope: calendar, documents, email marketing, a kanban view, a customer portal and sales automation. That is a conventional CRM feature set, and the interesting question is not what it does but who ends up running it.

The README answers that directly. It names startups, small and medium-sized businesses and larger organizations, then adds developers and anyone who wants a free or on-premise CRM. Those last two groups are the real audience. A team that only wants a hosted CRM with a support contract is not the target; a team that wants the database on its own hardware, and the entity model under its own control, is.

The reason is the extension model. The README describes EspoCRM as "more than a CRM, it's a platform for building custom business applications." That claim is the differentiator. If your sales process does not fit a fixed schema, the value is in adding the entities and relationships you need rather than bending your process to the product.

The PHP REST backend and the SPA frontend

The architecture is stated plainly: a web application with a frontend designed as a single-page application and a REST API backend written in PHP. The repository layout backs that up. There is an application/ directory for backend code, a client/ directory for the frontend, a schema/ directory, an install/ directory, and entry points at the top level including index.php, cron.php, daemon.php, websocket.php, rebuild.php, clear_cache.php and upgrade.php. Those filenames tell you how the thing is operated: a web entry point, a scheduler, a background worker, a websocket process, a cache clear and an upgrade runner.

On the backend, the README says the codebase adheres to SOLID principles, uses interfaces, static typing and generics, and that PHPStan runs at level 8. It recommends starting with the Dependency Injection article in the documentation. Metadata is described as playing an integral role, with all possible parameters described by a JSON Schema so an IDE can autocomplete them, and a full metadata reference in the docs. In practice that means the entity model is data, not code you patch: you describe fields, relationships and buttons in metadata and the application reads it.

The frontend is an SPA on a custom framework, using nested views and service dependency injection, with the core partially written in TypeScript. The README is honest that developers mostly work with existing form and field view implementations rather than writing a frontend from scratch. That is a real constraint: extending the UI means learning this framework, not reaching for a familiar one.

Installing EspoCRM and creating a first custom entity

The README does not print install commands. It points to four documented routes: manual installation, installation by script, installation with Docker, and installation with Traefik. Requirements are explicit: PHP 8.3 to 8.5, MySQL 8.0 or later, or MariaDB 10.3 or later, or PostgreSQL 15 or later. Start by reading the manual installation page, because the script and Docker paths assume the same server configuration article the README links to.

If you work from a git checkout rather than a release archive, the build is driven by Composer on the PHP side and npm on the frontend side. The package.json scripts give the exact commands, so there is no need to guess at a task runner.

composer install
npm install
npm run build

composer install pulls the PHP dependencies, npm install pulls the frontend toolchain and runs a postinstall cleanup step, and npm run build invokes Grunt to produce the frontend bundle. The README recommends downloading a release from the website or from GitHub releases for a normal deployment; the build path is for working from source.

Once the instance is up, the extension surface is metadata. The developer documentation describes parameters through JSON Schema and keeps a full metadata reference, so the workflow is to define a custom entity and its fields there and then run the rebuild so the application picks up the change. The repository includes rebuild.php at the top level for exactly that.

php rebuild.php

If you are evaluating rather than deploying, the README offers an online demo at espocrm.com/demo, which is the cheapest way to see the interface before touching a server. There is also a REST API, described as straightforward, which is the integration point for anything outside the application.

Where EspoCRM is the wrong tool

The licence is the first hard boundary. EspoCRM is AGPL-3.0, and package.json records AGPL-3.0-or-later. That is a strong copyleft licence with a network clause. If you modify EspoCRM and let users interact with it over a network, the AGPL's terms reach that deployment in a way the plain GPL's do not. For an internal CRM this is usually a non-issue; for a product you intend to distribute or offer as a service on top of modified code, it changes the calculus. This is not legal advice, and the LICENSE.txt in the repository is the document that governs.

The second boundary is operational. The README lists PHP, MySQL or MariaDB, and PostgreSQL as requirements, and the top-level files include cron.php and daemon.php. That means you are responsible for a PHP runtime, a database, a web server, a scheduled job runner and a background process. Teams without anyone who can debug a PHP stack will spend their time on the server instead of on customers. A hosted CRM removes that work, and for many small teams that is the correct trade.

Third, the frontend is a custom SPA framework. If your plan is to heavily restyle or rework the interface, the README's own guidance is that developers work with existing form and field views. Deep UI changes are possible but they are not the path of least resistance, and the documentation for that layer is thinner than for the metadata layer.

How EspoCRM differs from SuiteCRM and Odoo

The searches people run against this project cluster around comparisons, and the two most common are SuiteCRM and Odoo. The honest difference is in what each one asks you to learn.

SuiteCRM is the other long-standing open source PHP CRM. Both are PHP applications with a web interface and a database behind them, and both can be self-hosted. The divergence is the extension model. EspoCRM's README puts metadata at the centre, with a JSON Schema for parameters and a documented metadata reference, and describes the backend as following SOLID with interfaces and static typing. That is a modern PHP codebase with a declarative configuration layer. SuiteCRM carries a much longer history, and its customization story is shaped by that history. If your team already knows one of them, the switching cost is real and probably outweighs the architectural difference.

Odoo is a different animal. It is an ERP suite with a CRM module among many, built on Python, so choosing it usually means adopting the wider business application stack rather than just a CRM. If you only need leads, contacts, opportunities and support cases, Odoo brings modules you will not use. If you need accounting and inventory next to your CRM, the comparison flips.

There is also a licensing difference worth noting: EspoCRM is AGPL-3.0, which is more restrictive for network deployments than the permissive licences some alternatives use. That single fact can decide the choice before any feature comparison does.

Maintenance, upgrades and what the repository shows

The repository is not archived, and the last push was on 2026-09-23. Recent releases are close together: 10.0.6 on 2026-08-20, 10.0.7 on 2026-09-03 and 10.0.8 on 2026-09-08. The pattern is frequent patch releases within the 10.0 line rather than long gaps.

The README describes the branch model, and it is worth reading before you file a pull request. The fix branch is for upcoming maintenance releases and takes minor fixes. The master branch is the develop branch and takes new features. The stable branch holds the last stable release. If you run from a release archive, you follow the upgrade.php entry point and the release notes on GitHub.

Upgrade cost has two parts. The first is the version matrix: PHP 8.3 to 8.5 and the three supported databases define what your host must provide, and that matrix moves with major releases. The second is your own customizations. Because the extension model is metadata and custom entities, the surface you maintain is your metadata plus any extensions, not a patched core. That is a better position than a forked codebase, but it is not free: a major upgrade can still require changes to custom views or extensions that touch internals.

The CLA is the other maintenance-adjacent fact. The README states that a pull request cannot be merged until you accept the contributor licence agreement. If you plan to contribute fixes upstream, do that first rather than after writing the patch.

Editorial conclusion

Adopt EspoCRM if you want an on-premise CRM whose entities and fields you can change without forking, and you have someone comfortable with PHP 8.3 to 8.5, Composer and a MySQL, MariaDB or PostgreSQL instance. Do not adopt it if you need a vendor to run the servers, or if you cannot accept AGPL-3.0 terms for anything you distribute. Before committing, verify three things against your own environment: that your PHP and database versions fall inside the documented ranges, that the manual installation guide's file permissions match your web server, and that the metadata layer can express the entity and relationship you actually need, since that is the extension path the developer documentation points you at.

Frequently asked questions

Official sources

1. espocrm/espocrm on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases