Why EspoCRM extension compatibility decides your upgrade plan
Before you upgrade a self-hosted EspoCRM, check every extension against the target release, then prove the upgrade in staging before production. Each extension package declares the EspoCRM versions it accepts and the PHP versions it supports as SemVer ranges in its manifest, through acceptableVersions and the PHP range. Compare those declared ranges with the release you are targeting, and treat any extension without a range that covers the target as an open risk, not a pass. Your inventory should also include custom code in the custom directory, because that code is not covered by any manifest and can break even when every extension reports compatibility.
EspoCRM 9.0.0 was released on January 20, 2025, and 10.0.0 followed on July 2, 2026, according to the espocrm/espocrm releases page. Version 10.0 also disables upgrades through the web interface by default, so the upgrade runs through the command line and the planning work has to be finished before anyone touches the server. Confirm with your own admin team whether the 10.0 upgrade will be run from the CLI on your servers, and who signs off on each step.
Plan the sequence so that extension owners, custom code and PHP are all confirmed for the target release before the database is changed. A failed extension in production is much harder to recover from than a failed rehearsal in staging. Keep a tested backup, run the upgrade on a copy of production data, and record which extensions were updated, replaced or removed. The sibling pages on the 9 to 10 upgrade and on PHP cover the release-specific details.
What changes in EspoCRM 10 that affects extensions
This table lists the EspoCRM 10 changes that bear on extension compatibility and the action each one requires before you upgrade. Read each row as a checkpoint to clear in staging, not as a complete list of breaking changes. The main takeaway is that the supplied release facts do not name removed APIs, so the deprecation review must come from the official release notes for your target version.
| Change | Impact | Action needed |
|---|---|---|
| EspoCRM 10.0.0 released July 2, 2026 | Extensions built for 9.x may not declare 10.x in their acceptableVersions range | Check each extension's manifest and vendor release notes for 10.x support before scheduling the upgrade |
| EspoCRM 10.0.10 released October 14, 2026 | Later 10.0.x patch releases may change compatibility, so a test against 10.0.0 may not cover the version you deploy | Confirm the exact patch version you will run and test extensions against that version |
| UI upgrades disabled by default in 10.0 | Upgrades must run through the command-line process, so extension installs and updates are done outside the admin interface | Plan a CLI-based upgrade runbook and confirm the steps in the official upgrade documentation |
| Deprecated backend and frontend APIs | Custom extension code that calls APIs removed or changed in 10.0 can fail after the upgrade | Confirm the deprecated backend and frontend APIs in the official release notes for the target version, then scan extension code against that list |
| Extension manifest acceptableVersions (SemVer range) | An extension outside its declared EspoCRM range may be blocked or may fail at runtime | Read the acceptableVersions field in each manifest and compare it with the target version |
| Extension manifest php versions (SemVer range) | An extension that does not declare your target PHP version may fail after the PHP upgrade | Compare the declared PHP range with the PHP version required by the target EspoCRM release |
| Custom code in the custom directory | Custom code is not covered by vendor compatibility declarations and must be re-tested | Inventory custom code, review it against the release notes and run it in staging |
How acceptableVersions and PHP ranges in manifests decide compatibility
An EspoCRM extension manifest declares two things that matter during an upgrade: the EspoCRM versions the extension accepts, and the PHP versions it supports. Both are written as SemVer ranges, the same version-range notation used across most package ecosystems. Before any upgrade, open the manifest of each installed extension and record both ranges next to the target EspoCRM version and the PHP version you plan to run. The server configuration docs list PHP 8.3 to 8.5 as supported, so a PHP target inside that window is a starting point, but the extension's own range is what determines whether its author has declared support. Check the database requirements in the same pass: the docs list MySQL 8.0 or newer, MariaDB 10.6 or newer, or PostgreSQL 15, and an extension that assumes a specific database behavior should be noted against that list.
A range that excludes your target does not prove the extension will break, and a range that includes it does not prove it will work. Treat a mismatch as a signal to test in staging, and treat a missing or outdated range as a question for the vendor. For each extension whose range excludes the target EspoCRM version or PHP version, ask the publisher in writing whether a compatible release exists, when it is planned, and which parts of the extension were tested against the new version. Keep the answer with the upgrade plan. If the publisher is the EspoCRM project itself, the official extension releases on the espocrm/espocrm releases page are the first place to look for a matching build. For extensions from third parties, the manifest is the author's declaration only, so the staging test remains the real evidence.
Confirm the exact ranges from the extension package itself rather than from memory or a marketplace listing, because the manifest is what the EspoCRM installer reads. Record the EspoCRM and PHP versions that each extension was last verified against, and note any extension that has no declared range at all. Those entries deserve the most attention in staging, since the manifest offers no guidance on what the author expected. This inventory becomes the input for the test matrix and tells you which extensions can move with the core upgrade and which need a decision before the change window.
Four checks to run on every extension before the upgrade
Extensions are where most EspoCRM upgrades stall, because each one carries its own version promises and its own code. The four checks below cover where an extension came from, what versions it declares, what PHP it needs, and whether your own code sits alongside it. Run them together for every extension, and record the answers before anyone touches the staging copy.
Confirm the extension's origin
Start by sorting every installed extension into official, third-party or built in-house. Official extensions are published by EspoCRM itself, and the Advanced Pack is one example that ships with all EspoCRM Cloud plans. For third-party and internal packages, ask the publisher which EspoCRM releases they have tested and who maintains the package if the publisher stops. Record the owner and contact for each one, because that person is the one who answers compatibility questions during the upgrade.
Read the manifest version ranges
Each extension manifest declares the EspoCRM versions it accepts, written as SemVer ranges. Compare the declared range against the target version, not only the version you run today. If the range stops below the target, the extension may refuse to install or may be unsupported on the new release. Treat a missing or outdated range as an open question for the publisher, and note which extensions block the upgrade path.
Check the PHP range and modules
The manifest also declares the PHP versions an extension supports. Set that range against the PHP version your target EspoCRM release requires, and confirm which PHP extension modules the package depends on. A package that is compatible with the EspoCRM version can still fail if its PHP range or required modules are missing on the new server. Ask the publisher for a test result on the exact PHP version you plan to run, and plan the PHP upgrade in the same staging cycle.
Find custom code in the custom directory
Custom entities, layouts, hooks and scripts that your team wrote usually live in the custom directory, and they are not covered by any vendor's compatibility statement. Search that directory for PHP and JavaScript files that call internal classes or deprecated APIs, and list each one with its author. Custom code can break even when every extension passes, so it needs its own test cases in staging and a named owner who signs off on the result.
How official extensions and custom code differ in upgrade risk
Official EspoCRM extensions, such as the Advanced Pack, Sales Pack, Google, Outlook, Zoom and Stripe integrations, are maintained by the EspoCRM project. Your first task is to confirm, for each one, which EspoCRM version it supports in the release you plan to move to. Do not assume compatibility from the extension's name or from the core upgrade announcement. The extension's listing and release notes are the place to check, and the vendor's answer should be recorded in your upgrade plan. The Advanced Pack is included in all EspoCRM Cloud plans, which matters if you are comparing self-hosting with the cloud service, but it does not change how you verify compatibility on your own servers.
- Confirm the supported version: Check the extension's page and release notes against your target EspoCRM version and PHP version.
- The fix usually comes from the project: When an official extension breaks, the expected path is a newer official release, so track availability before scheduling the upgrade.
- Configuration still needs testing: Official extensions can change entity definitions, workflows or layouts that your customizations depend on.
- Test the features your teams use: Reports, BPM workflows, sync jobs and email integrations should each have a scripted check in staging.
- Record the approved versions: Keep a list of extension versions tested against each EspoCRM release.
Before you commit to a window, confirm in writing with the vendor or in the release notes which official extension versions support your target release.
Third-party extensions are built by partners, freelancers or your own vendors. Their upgrade risk is the highest of the three groups because compatibility depends on the author's maintenance, not on the EspoCRM project. An extension package declares the EspoCRM versions it accepts and the PHP versions it supports through the acceptableVersions and php fields in its manifest, using SemVer ranges. Read those ranges before you upgrade, but treat them as the author's claim until you have tested the package yourself.
- Read the manifest ranges: Compare the acceptableVersions and php entries against your target EspoCRM and PHP versions.
- Ask who fixes it: Confirm whether the author is still maintaining the package and how fast they respond to breaking changes.
- Check the source and license: Confirm you have the code, the license terms and the right to patch it if the author stops maintaining it.
- Test every extension separately: A single failing package can block the whole upgrade, so test each one in staging and note its result.
- Plan for a fallback: Decide in advance whether you will replace, rebuild or retire an extension that cannot be made compatible.
Before you upgrade, ask the author or your vendor to confirm the target versions in writing, and keep a copy of the package you tested.
Custom code in the custom directory, along with hooks, custom entity definitions and scripts, belongs to your organization. No one outside your team will fix it when it breaks, so the work of verifying it falls on you or your implementation partner. Custom code is also where deprecated or removed internal interfaces are most likely to be called, so it needs a review against the release notes for each version between your current and target release, not just a smoke test. Keep the custom directory under version control so you can see exactly what changed and roll it back.
- Inventory every file: List the files in the custom directory, every hook, and every custom entity definition, with an owner for each.
- Review against release notes: Check each custom file for calls to APIs listed as deprecated or removed in the target release.
- Version control the custom directory: Track changes in Git so you can compare the staging and production code before cutover.
- Write scripted tests for hooks: Verify that before-save and after-save logic still runs and produces the same field values.
- Assign the fix owner: Name the person or team who will patch each custom file if a test fails.
Before the upgrade, confirm that every custom file has an owner, a test and a rollback path.
The extension-first upgrade sequence with rollback points
This sequence turns an EspoCRM upgrade into a series of checked stages, so extension and custom code breakage is found in a staging copy with a verified backup to return to, not in production.
Inventory extensions and custom code
Your administrator and the implementation lead list every installed extension with its installed version, every file in the custom directory, and every before-save script, workflow, BPM process and integration that depends on them. Record which teams own each item and whether a vendor or an in-house developer maintains it. The step is done when the inventory is a single document that another engineer could use to rebuild the environment, and when each item has an owner.
Check manifests and PHP requirements
For each extension, compare the acceptableVersions range and the supported PHP versions declared in its manifest against the target EspoCRM release and the PHP version you run or plan to run. Confirm the target PHP version against the EspoCRM server configuration documentation. Items with no matching range, or with a range that excludes the target, go on a blocker list. The step closes when every extension is marked compatible, blocked or unknown, and each unknown has a named owner who will confirm it with the publisher.
Obtain target-version builds
Request or download the target-version release of each official and third-party extension from its publisher, and confirm the release notes for breaking changes. Where a publisher has no build for the target version, decide whether to replace the extension, pin the current EspoCRM version, or remove the dependency. Store the packages with checksums in your change record. The step is complete when every extension you intend to keep has a matching package for the target release and the decision for each gap is written down.
Take a tested backup and set the first rollback point
Before any change, take a full backup of the database and the file directory, including custom code and uploaded files, and restore it to a separate host to confirm it works. Record the EspoCRM version, PHP version, extension versions and the backup identifier. This is the first rollback point. The step is done when the restore has been tested and the recorded state is enough to rebuild the instance without guessing.
Upgrade a staging copy through the CLI
Build a staging copy from the production backup, on the same server configuration and PHP version as the planned production target. Because the UI upgrade is disabled by default in 10.0, run the upgrade through the command line process described in the EspoCRM upgrade documentation, and install the target-version extensions in the order your manifest checks allow. Record each error and warning. The step is complete when the upgrade finishes and the staging instance loads without fatal errors in the logs. This is the second rollback point: if the staging result is unacceptable, you return to the backup and revise the blocker list.
Run regression tests on scripts, workflows and integrations
Test the parts most likely to break against the staging copy: Formula Script before-save scripts, workflows and BPM processes, the scheduled jobs that run them, and the integrations that depend on them. Include OIDC sign-in with a test user and a fallback login, LDAP bind if you use it, and API calls made with each API user through its authentication method. Compare results with the pre-upgrade baseline. The step closes when every test case has a recorded pass or a logged defect with an owner, and no critical defect is open.
Schedule production with a fresh backup and go or no-go review
Agree a maintenance window with the business owners of the affected teams. Immediately before the change, take a new backup of production and confirm its restore, since the staging backup no longer reflects live data. Hold a go or no-go review using the staging results and the blocker list, and name who can authorize a rollback. The step is done when the review decision and rollback owner are recorded and the production upgrade is approved in writing.
Preparing the inventory and staging copy
Extension compatibility is only as good as the inventory behind it. These four cards cover what to capture, how to copy it safely, and how to prove the copy behaves like production before anyone touches the live instance.
Full backup, restore-tested
Take a complete backup of the database and the file system, including the custom directory, uploaded files and the data directory, then restore it to a separate host. A backup that has never been restored is only a hope. Confirm that the restored copy logs in, loads records and runs background jobs before you rely on it as a rollback point.
Inventory of installed extensions
List every installed extension with its version, the EspoCRM version it declares as acceptable, and the PHP versions it lists. Record whether each one is an official release, a third-party package or a custom build. Compare this list with what the instance actually reports, because extensions copied into place by hand often do not appear in the admin screens.
Entity Manager and layout customizations
Export a record of every custom entity, field, relationship, layout and list view, along with the role and team settings that expose them. Entity Manager and layout changes live in configuration files and the database, so an upgrade can surface them in unexpected ways. Note which items were created by an extension and which were created by your team.
Formula scripts and hooks
Catalog every Formula Script in before-save scripts, API before-save scripts, workflows and BPM processes, and every custom PHP hook in the custom directory. Mark any script that calls an API or depends on a field name or default value. These are the places where a version change to core behavior will most likely break a business rule without raising an error.
Staging copy matching production
Build a staging instance with the same PHP version, extension modules, database engine and version, web server and cron setup as production. Restore the production backup into it, then apply the same configuration. Differences in PHP or database versions can cause failures that look like extension bugs, so match the stack before judging any result.
Test script for critical paths
Write a short test script covering the paths users rely on: logging in through the identity provider, creating and editing records in key entities, running a CSV import in Update Only mode on a sample file, calling the REST API with each API user's authentication method, and triggering a workflow and a scheduled job. Run it on staging before and after the extension updates, and log every failure against its extension or custom script.
What makes extension compatibility work longer or shorter
This table compares the factors that expand or shrink the compatibility check before an EspoCRM upgrade. Read each row as a direction of effort and use the right-hand column as the list of items to confirm in your own instance. The main takeaway is that custom code and integrations usually drive the work more than the raw count of extensions.
| Driver | Effect on effort | What to check |
|---|---|---|
| Number and type of extensions | Each extra extension adds a manifest check and a test pass; paid or third-party extensions add a vendor release to confirm | Inventory every installed extension, its version, its acceptableVersions range and whether it is an official release |
| Custom code in the custom directory | Usually the largest driver; hooks, controllers and services that call changed or removed APIs need line-by-line review | Search custom code for calls to deprecated backend and frontend APIs listed in the target version's release notes |
| Formula Script in workflows and BPM | Scripts run on save and in automations, so breakage can appear in business processes rather than on screen; effort rises with script count | List every before-save script, API before-save script, workflow and BPM process that uses Formula Script and run each one in staging |
| Integrations and API users | Each integration needs its API user, auth method and payload tested; HMAC or API key integrations are typically simpler to verify than basic authentication | Confirm each external system's expected endpoints, authentication method and permissions for the dedicated API user after upgrade |
| PHP module changes | A higher PHP requirement can force a runtime change that also affects extensions with their own PHP dependencies | Compare the PHP versions in each extension manifest against the target version's supported range and check installed PHP modules |
| Data volume and environment count | Larger datasets lengthen staging rebuilds and test runs; more environments (dev, staging, production) multiply the work | Confirm record counts, the backup and restore time in staging, and whether each environment has the same extensions and custom code |
Questions teams ask before checking extensions
Can our own team check extension compatibility before an EspoCRM upgrade?
Yes, if you have someone who can read extension manifests, run the upgrade in a non-production copy and test the business processes that depend on each extension. Each extension declares the EspoCRM versions and PHP versions it supports using SemVer ranges, so the first check is a comparison between those ranges and your target version and PHP runtime. The harder part is testing. Official extensions usually have newer releases, but custom extensions and code in the custom directory need hands-on testing against the new version. Your team should confirm the support status of every extension with its publisher before deciding whether to do this in-house or bring in a partner.
What do we need to provide before an extension review starts?
Most of the effort is in preparation, so the more you have ready, the less time the review takes. You will need an inventory of every installed extension with its current version, the source of each one (official release, marketplace package or in-house code), and a list of custom code in the custom directory. You also need a staging environment that matches production as closely as possible, a current, tested backup, access to the server and database, and a named owner on your side who can make decisions about which extensions to keep, replace or retire. Without an owner, open questions tend to stall the work.
How does the cost of an extension check depend on our setup?
DeployOpen does not publish a price list. A quote follows from a written scope, and the scope drives the cost. The main factors are the number of extensions, how many are custom or unmaintained, how much custom code needs review, how many PHP and database versions are involved, and how much staging testing is required. Fixed-scope work is agreed in writing before it starts. Ask for a quote that separates the one-time compatibility review and staging tests from any later support or retainer work. For reference, EspoCRM Cloud prices of 15, 25 and 69 US dollars per user per month, from the EspoCRM pricing page, apply to the hosted service only and do not cover self-hosted deployments.
How long does an extension compatibility check take?
The duration depends on how many extensions you run, how many are custom, and how much of your business logic they touch. An instance with a few official extensions and little custom code will take far less time than one with several in-house extensions, custom hooks and formula-driven workflows that all need testing. Other drivers include whether a compatible release exists for each extension, how quickly publishers respond, and how long your team takes to approve test results. Ask for a timeline that lists the review, staging test and sign-off phases separately so you can see which steps depend on third parties.
What should we do if an extension has no release for the new version?
You have three practical options. You can wait for the publisher to release a compatible version, you can replace the extension with an alternative or an official module, or you can keep the current EspoCRM version until the dependency is resolved. If the extension is custom, the choice is whether to port it to the new version, which means reviewing deprecated APIs and retesting its behavior. Do not upgrade production while an extension you depend on is unsupported. Record the decision, the affected users and the test results so the change is traceable. The right choice depends on how central the extension is to your processes.
Can we roll back an EspoCRM upgrade if an extension fails?
A rollback is only realistic if you take a complete, tested backup before the upgrade and confirm you can restore both the database and the file system. Test the restore in staging first, so you know how long it takes and that the extensions and custom code come back in the expected state. Keep the previous PHP version and extension packages available until the upgrade is accepted. Note that the EspoCRM security documentation says upgrading through the UI is disabled by default as of version 10.0, so plan around the command-line upgrade process and your own change window. Confirm the restore procedure with your team before the production change date.
How DeployOpen scopes and delivers an extension compatibility review
DeployOpen scopes an extension compatibility review as a fixed-scope engagement, with the scope, deliverables and timeline agreed in writing before any work starts. The written scope usually follows the sequence that matters for an upgrade: an inventory of every installed extension and every file in the custom directory, a review of each extension's manifest for its declared acceptableVersions and PHP ranges, a check of whether each extension has an official release for the target EspoCRM version, and a staging upgrade with defined test cases for the workflows your teams depend on. The inventory is the input that drives the rest of the scope, so the number of extensions, the amount of custom code and the number of integrations are the first things a quote will reflect. Ask the partner to list exactly which of these items are included and which are excluded, including any remediation of custom code that the review uncovers.
Ongoing support is available as a retainer for teams that need help after the review, such as repeated staging runs before each release, production support during the upgrade window, or follow-up when a new extension version changes its compatibility range. DeployOpen does not publish a price list. A quote follows from the written scope, so the reader should expect the quote to itemize the inventory, review, staging, testing and production stages separately, and to state which of them recur. When comparing a partner with an internal team, ask each bidder to describe the test cases they will run, who signs off on staging results, and what happens if a required extension has no release for the target version.
