How to plan an EspoCRM 8 to 9 upgrade for a live CRM
Upgrading a live EspoCRM 8 install to 9.0.0, released on January 20, 2025, is a planned change to three things at once: the application itself, the extensions and custom code layered on top of it, and the PHP runtime it runs on. Treat it as a change project with a rollback plan, not a file swap. Follow the documented upgrade procedure in the EspoCRM upgrading docs, and before you fix the sequence, confirm in those docs whether any 8.x releases sit between your current version and 9.0.0, since each step may carry its own requirements.
Start with an inventory. List every installed extension with its version, every file under the custom directory, every API integration and the API users behind it, and every before-save script or workflow your team depends on. Then check the PHP version your server runs against the range the target release requires, and list the PHP extension modules your installed extensions rely on so they can be reinstalled or verified on the new runtime. Ask each extension vendor for a 9.0.0 compatible release. Where none exists, that extension becomes a blocking decision for the business owner, not an afterthought for the upgrade day.
Set the test and backup order before anyone touches production. Take a full database and file backup, then restore it to a staging copy and run the upgrade there first. Test the flows your sales and service staff use daily: lead conversion, email sending, login through your identity provider if you use OIDC or LDAP, and any scheduled jobs that depend on cron. The new 9.0.0 features, including collaborators, multiple assigned users enabled through the Entity Manager, and app secrets, change how records behave, so ask a few power users to review those areas. Agree a rollback window and a named owner for the go or no-go call before the production date is set.
What EspoCRM 9.0 changes and what each change means for your install
This table lists the features EspoCRM 9.0.0 introduced and what each one means for an existing 8.x install. Read each row against your data, layouts, custom code and role design, then decide whether to enable the feature deliberately or leave it off until it is reviewed. Breaking changes for custom code and extensions are not listed here and must be confirmed separately.
| Change in 9.0.0 | Impact on existing data, layouts, code or access | Action for the admin team |
|---|---|---|
| Collaborators | Records can gain collaborators who see or work on them without being the assigned user. Existing records do not gain collaborators automatically, but access rules for those records may need review. | Decide which entities need collaborators, then check role permissions on those entities before users start adding people. |
| Reactions | Users can react to records or stream posts. This adds new activity to the stream and does not change stored field values. | Confirm with business owners whether reactions suit the team's stream use, and communicate the change to users. |
| Scheduled email sending | Emails can be queued for a later send time. Scheduled jobs must run for queued emails to go out, so cron or the scheduled task must be working. | Verify background jobs run on the upgraded server and test a scheduled email in staging before relying on it. |
| Web-to-lead forms | Lead capture forms can be published from EspoCRM. Forms create lead records, so new public input reaches your database and must follow your data handling rules. | Review the fields, consent wording and spam controls before publishing any form, and check who receives new leads. |
| Viewing user access | Admins can review what a given user can access. This is a read-only aid for reviewing roles and does not change permissions by itself. | Use it during the upgrade to compare intended access with actual access for key roles, especially API and portal users. |
| App secrets | Sensitive values used by integrations can be stored as app secrets instead of plain settings. Existing integration settings may need to be moved and tested. | Inventory every integration credential, move them to app secrets where supported, and confirm integrations still authenticate after the upgrade. |
| Multiple assigned users | Entities can hold more than one assigned user. This is turned on through an Entity Manager parameter, and it changes how assignment fields, filters and workflows behave on that entity. | Leave it off by default. Enable it only on entities where the business needs it, then retest layouts, filters, workflows and any custom code that reads the assigned user field. |
What to prepare before touching the 8.x install
Most failed EspoCRM upgrades trace back to work skipped before the upgrade started. The five cards below each produce a decision or a piece of evidence, and together they give you a rollback point, a list of what could break, and a tested copy to upgrade first.
Take a tested full backup
Back up both the application files and the database, then restore that backup to confirm it works. A backup that has never been restored tells you little about recovery. Record the EspoCRM version, the database engine and version, and the file locations so the restore can be repeated exactly. Keep this backup as your rollback point until the upgraded instance has run through your full business cycle. Use the upgrade guide to confirm the backup steps for your install method.
Inventory custom entities and layouts
List every custom entity, field, layout, relationship and dynamic logic rule created in the Entity Manager and layout editor. Note which items were built by hand and which came from an extension, because extension-owned items may be reset or changed by the extension's own update. This inventory tells you what to retest after the upgrade and which items need a second review against the new 9.0 features.
Review formula scripts and custom code
Export every Formula Script used in before-save scripts, API before-save scripts, workflows and BPM processes, and collect any PHP files in the custom directory. Formula scripts often depend on field names and link behavior, so changes to those areas can break them silently. Mark each script as keep, adjust or retest, and keep copies outside the live install so you can compare before and after.
Build an extension inventory with versions
Record each installed extension with its installed version, its vendor, and the EspoCRM versions it declares as compatible. Check whether a 9.0 compatible release exists for each one before you schedule the upgrade. An extension without a matching release becomes a decision point: upgrade it, replace it with a core feature, or remove it. Confirm this list against your own instance because versions vary by install.
Check PHP against the server docs
Compare the PHP version on your server with the requirements in the server configuration docs, which list PHP 8.3 to 8.5 for current releases. Confirm the exact PHP requirement for 9.0 in the 9.0.0 release notes and upgrade docs before you change anything. Also check the required PHP extensions and the database versions, since a missing module can stop an upgrade midway.
Restore a staging copy first
Restore the fresh backup to a separate server with the same PHP, database and web server setup, then run the upgrade there. Test login, the custom entities, workflows, scheduled jobs, email and each extension against real records. The staging result decides whether the production upgrade goes ahead, and any problem found there is cheaper to fix than one found in live data.
The upgrade sequence, with checks and rollback points
This sequence moves a production EspoCRM 8 instance to 9.0 only after a verified backup, a rehearsal on staging, and checks on PHP, extensions and key workflows. Each step ends with a check that tells the team whether it can move forward or must roll back.
Freeze changes on the source instance
The client's CRM administrator announces a change freeze for the EspoCRM 8 instance, covering customizations in the Entity Manager, layout edits, workflow changes and extension installs. Changes made during the rehearsal would not be carried into the upgrade, so the freeze keeps the staging and production runs comparable. The step is done when the administrator confirms in writing that no changes are pending and the freeze window is recorded. Rollback point: none is needed yet, since nothing has been altered.
Take and verify a full backup
The implementation engineer takes a full backup of the database and the files directory, using the backup command in the command.sh utility if the instance was deployed with the Docker-based install script, or the equivalent procedure for the chosen server stack. The backup is then verified by restoring it to an isolated host and confirming that a sample of records, attachments and users is present. The check is a successful restore report and a login test. Rollback point: this backup is the reference for every later rollback, so it is stored off the production host.
Restore the backup to staging
The engineer restores the verified backup onto a staging host that matches production in PHP version, database engine and web server, so the rehearsal reflects the real environment. Cron or the scheduled task is configured on staging as it is in production, so background jobs run during testing. The step closes when the staging instance loads, the system settings match production and the database version is confirmed. Rollback point: staging can be rebuilt from the same backup at any time without touching production.
Align PHP and required extensions
The engineer checks the PHP version and installed modules against the EspoCRM 9.0 server requirements, and reinstalls any missing PHP extension modules on staging first. PHP 8.3 is the minimum listed for the current server configuration, so an older PHP build must be upgraded before the EspoCRM files are replaced. The check is a PHP information report showing the required version and modules. Rollback point: the PHP change is made on staging and kept in a configuration record, so it can be reverted without affecting the production PHP setup.
Upgrade extensions to 9.0-compatible versions
Each installed extension is compared with the version it declares as compatible with EspoCRM 9.0, and the engineer obtains a compatible release from the vendor or the extension author. Custom code in the custom directory is reviewed for use of APIs that changed between versions, and affected files are adjusted on staging. The step is done when every extension has a documented version and a clean install on staging. Rollback point: extensions that have no 9.0-compatible release stay on the 8.x branch, and the upgrade decision is made before production is touched.
Run the CLI upgrade on staging
The engineer runs the upgrade through the documented command-line procedure on staging, following the order in the EspoCRM upgrade documentation, then clears caches and rebuilds as instructed. The output log is saved and any error is traced before the next step. The check is a successful upgrade log, a version number of 9.0 shown in the administration panel, and no errors in the application log. Rollback point: the staging instance is restored from the backup and the procedure is repeated after the fault is fixed.
Run smoke tests on key workflows
The business owners and the engineer test the workflows that matter most: lead capture, record creation and assignment, email sending, reports, portal access, login through the chosen single sign-on method and any integrations. Testers use the test accounts and roles that match production users. The step closes when each listed workflow passes and the results are signed off by the business owner. Rollback point: any failed workflow stops the production schedule until it is corrected on staging and the staging upgrade is rerun from the backup.
Schedule the production window and repeat the sequence
The client and the engineer agree a production window with users informed in advance and a named contact for go or no-go decisions. On the day, the engineer repeats the backup, verification, PHP alignment, extension upgrade and CLI upgrade steps on production, using the staging log as the checklist. The check is the same post-upgrade result seen on staging, plus a successful smoke test on production records. Rollback point: if the production upgrade fails, the production backup taken at the start of the window is restored and the window is closed.
Confirm cron and background job checks
After the upgrade, the engineer confirms that cron or the scheduled task is running, that background jobs such as scheduled emails, workflows and report jobs are processed, and that the job queue does not show a growing backlog. The engineer also reviews the application log for recurring errors over the first monitored period. The step is done when the operations owner accepts the production instance in writing. Rollback point: if jobs fail after the window closes, the team uses the production backup as the last known good state and reviews the logs before any second attempt.
How to test the upgrade and roll back if it fails
Decide the rollback rule before the upgrade window opens, not during it. Agree in writing who calls the go or no-go, which checks must pass on staging, and the point after which you stop trying to fix forward and restore. Staging should be a copy of production with the same EspoCRM 8.x version, the same PHP and database versions, the same extensions and a recent copy of real data (handled under your data protection rules). Run the upgrade there first, then test the things most likely to break in a 9.0 move: login through your chosen method, including any OIDC or LDAP sign-in; role and team permissions for each user type, including API users; custom entities and their layouts; before-save Formula Script logic set in the Entity Manager; workflows and any Advanced Pack automations; CSV imports in the mode you use; outbound email; and every integration that writes to or reads from EspoCRM. Record each result, not just pass or fail, so the go decision rests on evidence.
A backup only protects you if it has been restored and checked. Take the production backup with the method your deployment uses, then restore it to a separate host or stack and confirm that the application loads, the database counts match, attachments open and a test user can sign in. Rehearse the full rollback path on staging: restoring the database, restoring the application files and any changes made in the custom directory or configuration files, and bringing background jobs back on. Those file-level steps are where rollbacks usually go wrong, because a database restore without the matching code can leave an instance that looks healthy but fails on the first write. Confirm the exact restore and upgrade commands in the EspoCRM upgrading documentation and the command.sh reference for your installation method, since these differ between script, Docker and manual installs. Write the rehearsed steps into the runbook with the names of the people who run them.
What makes an EspoCRM 8 to 9 upgrade take longer
This table lists the factors that most often extend an EspoCRM 8 to 9 upgrade and what each one adds to the work. Read each row as a question to answer about your own instance before you request a quote, because the answers decide how much review, testing and rollback planning the upgrade needs.
| Driver | Why it adds work | What to ask or measure |
|---|---|---|
| Custom code and formula scripts | Custom PHP hooks and Formula Script in before-save scripts, workflows and BPM must be checked against 9.0 behavior, including the new multiple assigned users option. | How many custom files sit in the custom directory, how many formula scripts exist, and which ones touch assignment fields? |
| Extensions and their age | Each extension needs a version that declares compatibility with 9.x, and older or unmaintained packages may need replacing or rebuilding. | Which official extensions are installed, such as the Advanced Pack, and does each custom extension package list a 9.x-compatible version? |
| Custom extension packages | Packages built in-house are not covered by vendor compatibility checks, so their dependencies and hooks need manual testing. | Who maintains each package, when it last changed, and is its source under version control? |
| PHP runtime and extension modules | EspoCRM 9 runs on a defined PHP range, so the server may need a runtime change and reinstalled PHP modules before the upgrade can start. | Current PHP version, installed modules, and whether the web server and cron jobs use the same PHP binary. |
| Database size and attachment volume | Backups, restore tests and the upgrade's database steps take longer as record and file counts grow, and the backup must be restorable before you begin. | Database size, number of attachments and their total storage, and how long a full restore took in your last test. |
| Authentication and integrations | OIDC or LDAP sign-in, API users, email and telephony connections each need re-testing because login, token and permission behavior is checked end to end. | How many identity providers, API users, mailboxes and telephony links are active, and which ones are used by other systems? |
| Roles, layouts and teams | Teams need to review roles and layouts to decide where the new 9.0 features, such as collaborators and viewing user access, should appear and who can use them. | Number of roles, layouts and teams, and which of them will change for collaborators, reactions, web-to-lead forms or scheduled email. |
How the upgrade differs by deployment method
The EspoCRM installation script for Ubuntu, Debian and Linux Mint deploys a Docker-based stack with Nginx and MariaDB, and it adds a command.sh utility for backups, restores and upgrades. This is the path where the vendor's own tooling does most of the work, so the main job is confirming that the tooling was used consistently since installation. Check the server configuration docs for the supported database versions, because a MariaDB release older than 10.6 would fall outside the supported range before you even start the upgrade.
- Backup mechanism: Take the backup with
command.shand keep a copy outside the host, then restore it to a separate server to prove it works. - Upgrade mechanism: Run the upgrade through
command.shrather than replacing containers by hand, so the stack stays in the state the script expects. - Environment to confirm: Ubuntu, Debian or Linux Mint release, Docker engine version, and whether Let's Encrypt renewal still works after the change.
- Background jobs: Confirm that the cron entry for EspoCRM jobs exists inside the expected container or host location.
- Main risk: Manual edits to compose files, Nginx config or environment variables made after installation may be overwritten or may conflict with the script's upgrade.
Before you start, confirm that the database and PHP versions inside the stack meet the supported ranges for EspoCRM 9.
A manual install on Apache, Nginx or IIS means your team built the PHP runtime, web server, database and file layout by hand. The upgrade is a file and database operation on a host you configured yourself, so the backup must cover the application directory, the database and any external file storage. The server configuration docs list supported PHP versions, database versions and web servers, and you should check each against your current host before planning the window.
- Backup mechanism: Take a database dump and a copy of the application directory, including custom code and configuration, and test a restore on a staging host.
- Upgrade mechanism: Run the EspoCRM upgrade from the command line, since the upgrade path depends on the file layout you created.
- Environment to confirm: Web server type and version, PHP version with its extension modules, MySQL 8.0 or newer, MariaDB 10.6 or newer, or PostgreSQL 15, and file ownership for the web user.
- Scheduled tasks: Confirm that cron on Linux or a scheduled task on IIS runs the EspoCRM job runner under the correct user.
- Main risk: Drift between the documented layout and the real server, such as a custom document root or a PHP version that differs between the web server and the CLI, can cause the upgrade to fail mid-way.
Verify the PHP binary used by cron matches the one used by the web server before the upgrade begins.
A Docker Compose stack separates the application, database and web layers into containers, and the state lives in named volumes or bind mounts. The upgrade therefore depends on preserving those volumes and the environment definitions while changing the image versions. Because containers are disposable, the risk is less about the code and more about data that sits in the wrong place or a database volume that is not included in the backup.
- Backup mechanism: Dump the database from its container and archive every volume that holds EspoCRM files, uploads and configuration.
- Upgrade mechanism: Pull the new image, recreate the containers with the same volumes and environment, and then run the upgrade steps inside the application container.
- Environment to confirm: Compose file version, volume names and mount paths, the database image tag, and the PHP version in the chosen EspoCRM image.
- Daemon and cron: Confirm that the job runner or daemon container runs with the same configuration after recreation.
- Main risk: Recreating a container without the original volumes or environment file silently starts an empty instance, so check the volume list before running any
downcommand.
Test the recreate step on a copy of the stack before touching production.
Questions buyers ask before an EspoCRM 8 to 9 upgrade
Is the EspoCRM open-source edition free to upgrade?
The open-source edition can be downloaded and self-hosted for free, according to the EspoCRM pricing page, so the software itself carries no license fee. The cost of an upgrade is the work around it: planning, extension checks, testing, backups and the maintenance window. Those costs come from your own staff time or from a partner's written scope. Paid EspoCRM Cloud plans and official add-ons are priced separately and are not required to run the self-hosted edition.
What drives the cost of an EspoCRM 8 to 9 upgrade?
The main drivers are the number of custom entities, layouts, formula scripts and hooks in the custom directory, the number of installed extensions and whether each one has a 9.x-compatible release. Deployment complexity matters too, including whether the instance runs on Docker, a bare-metal Nginx or Apache stack, and how many environments need to be upgraded. Ask any provider for a fixed-scope quote that lists each customization, extension, environment and test pass, so you can compare the work line by line.
How long does an EspoCRM 8 to 9 upgrade take?
The timeline depends on the scope: how much custom code needs review, how many extensions need replacing or testing, and how many staging rounds your business users need. Installs with few customizations move faster than instances with heavy formula logic, integrations and custom PHP. Confirm the schedule with your provider or internal team before you set a maintenance window, and ask for the milestones that will be checked in staging before production.
What does our internal team need to provide for the upgrade?
Your team should provide a current inventory of extensions, custom code and integrations, a list of test users who represent each sales and service role, and a maintenance window agreed with the business. You also need administrative access to the servers, the database, the cron schedule and the backup location. Without these inputs, testing will miss workflows that matter, and the rollback plan will be untested.
Can our team upgrade EspoCRM 8 to 9 without a partner?
A team with Linux and PHP administration experience can usually upgrade a simple install alone, provided it follows the EspoCRM upgrading documentation and tests in a staging copy first. The work gets harder when the instance has custom code, several extensions, database changes to review or multiple environments. Before deciding, check whether your team can build a staging copy, run the upgrade steps in order and verify every workflow your users depend on.
When is it worth bringing in a partner for the upgrade?
Bring in a partner when the instance includes custom entities, formula-driven business rules, workflows, integrations or a custom extension, or when no one on your team has run the upgrade before. A partner is also useful when the upgrade must be scheduled around regulated change control or when the next major version, 10.0, is already on the roadmap. Ask for a written scope that names the environments, extensions and test cases covered, and what is excluded.
Is our EspoCRM data at risk during the upgrade, and how does a backup protect it?
Any schema or code change carries some risk, so the data is protected by a complete backup taken before the upgrade and tested by restoring it to a separate server. The backup should include the database and the files your instance depends on, such as uploads and custom code. Confirm that you can restore it within the time your business allows, and keep the pre-upgrade copy until users have verified production for an agreed period.
Which EspoCRM 9.0 features should we review after the upgrade?
Version 9.0.0, released on January 20, 2025, added collaborators, reactions, scheduled email sending, web-to-lead forms, viewing user access and app secrets, and it enabled multiple assigned users through an Entity Manager parameter. Review how existing assignment fields, email processes and access rules behave after the upgrade, because enabling new features can change how records are shared. Note that the release notes list these features, so confirm the details against your own configuration in staging.
How DeployOpen scopes, delivers and supports the upgrade
DeployOpen plans and runs EspoCRM 8 to 9 upgrades inside your own infrastructure, starting with a written scope that covers your version, PHP runtime, extensions and custom code. Each step is tested on a copy of your instance before anything changes in production.
How we scope
- Inventory your current EspoCRM 8 version, PHP runtime, database and web server before agreeing the work.
- List every installed extension and custom file in the custom directory, with its compatibility status for 9.x.
- Agree in writing which 9.0 features you will enable, such as multiple assigned users, and which stay off.
How we build
- Take a tested backup of files and database, and confirm you can restore it on a separate host.
- Run the upgrade on a staging copy using the CLI process, then check PHP prerequisites and extension versions.
- Test custom formulas, layouts, workflows, integrations and API users against your real business processes.
How we hand over
- Deliver a runbook with the exact upgrade steps, rollback points and the backup and restore procedure used.
- Document extension versions, PHP settings and any configuration changed for 9.0, so your team can repeat the work.
- Walk your administrators through post-upgrade checks, including cron jobs, email delivery and login.
How we support
- Support after handover is available as a retainer, which you can scope to cover patching and later upgrades.
- Confirm with us how monitoring of background jobs and logs will be handled after the cutover.
- Ask us to plan the next major step, including the EspoCRM 9 to 10 upgrade, as a separate written scope.
