Dolibarr upgrade: checklist and upgrade path (16 to 24)

Many companies stay on the same Dolibarr version for years, for fear of breaking everything. The fear is justified, but it usually points at the wrong thing. It is almost never Dolibarr itself that breaks. It is what you added around it.

To check this, 45 free modules were installed on test Dolibarr instances, then really upgraded, version after version, up to 24: 280 version upgrades in total. The control instance, with no added module, went from 16 to 24 without a single fatal error. Every failure found came from the code of external modules. And 13 of these modules already had a fatal error before any upgrade, without anyone noticing.

So the risk sits in four places, always the same:

• external modules, the ones in the custom/ folder;
• the PHP version of your server;
• computed or conditional extra fields, and their filters;
• hidden settings and the variables of your e-mail and document templates, some of which have been renamed.

Before: the checklist

1. Write down your exact Dolibarr version and your PHP version. Both are shown in the system information pages of the admin tools.
2. Compare your PHP with the table below. Below the minimum, the upgrade wizard will offer you nothing. Above the highest planned version, it only shows a warning: it may work, but nobody tested it for you.
3. List your external modules, meaning everything in the custom/ folder. For each one, check that a version is announced as compatible with your target version, and get it before you start. This is the number one cause of failure.
4. Review your extra fields: computed ones, their display conditions and their filters. Several old syntaxes are no longer accepted (details version by version below).
5. Find the hidden settings you set in the advanced setup: a few have been renamed, and one has even had its meaning reversed.
6. Review your e-mail templates and your ODT document templates: some substitution variables have disappeared.
7. Make a full backup, and check that you know how to restore it. Full means: the database, the documents folder, the conf/conf.php file and the custom/ folder. A backup you have never restored is only a hope.
8. Rehearse the upgrade on a copy before touching the real instance. It is the only way to see the failures before your users do.

To save time on this checklist, the free module Upgrade readiness check runs most of these checks without changing anything: it reads the code of every external module against the target version, checks PHP, the database, computed fields and ODT templates, then gives you a report. It does not replace the backup or the test on a copy.

During: the procedure

You do not need to install every intermediate version: you install the files of the target version directly. The database, however, goes through every step: the upgrade wizard offers the migrations one at a time (16 to 17, then 17 to 18, and so on), and you must run all of them, in order.

In Docker, with the official image, it is different: the automatic upgrade skips migrations if you jump several versions at once. Read Upgrading Dolibarr in Docker first.

Over SSH, without the web wizard, the same migrations can be run from the command line, with a trap that blocks the second step without any error: see Upgrading Dolibarr from the command line.

1. Warn your users: nobody should be working in Dolibarr during the operation.
2. Make the full backup described above.
3. Replace the Dolibarr files with those of the new version, without overwriting conf/conf.php, the custom/ folder or the documents folder.
4. Delete the install.lock file, located in the documents folder. As long as it is there, the wizard refuses to open, and that is intended.
5. Open your Dolibarr address followed by /install/, then run each migration step offered, up to the target version.
6. Recreate install.lock at the end. Without it, anyone could restart the installation.
7. Open the screens you use every day: an invoice, a quote, PDF generation, the screens of your external modules.

If something no longer opens

A blank page or an HTTP 500 error right after an upgrade comes, in the vast majority of cases, from an external module. The PHP error log gives the file at fault: if it is in custom/, you have found the culprit.

If the modules screen no longer opens, you can disable the module directly in the database. Adapt the table prefix (llx_ by default) and the module name, and first look at what the query will touch:

SELECT name, value FROM llx_const WHERE name LIKE 'MAIN_MODULE_MODULENAME%';
DELETE FROM llx_const WHERE name LIKE 'MAIN_MODULE_MODULENAME%';

To roll back, always restore the database and the files together. Old files on top of an already migrated database are not blocked by Dolibarr, and that is precisely what makes it dangerous: everything seems to work, until the day a screen writes into a column that has changed.

Dolibarr upgrade path: versions 16 to 24

The minimum PHP is the one below which the upgrade wizard offers nothing. The highest planned PHP is only a warning threshold: above it, Dolibarr shows an alert but does not block. If one of the removed modules is still active on your instance, find a replacement before upgrading.

What changes, version by version

Only the changes that can affect a company using Dolibarr are listed here, not those that only concern core developers.

• 16: sensitive actions now require a security token, including in links. An old module that does not pass it sees its buttons refused. Triggers named …_UPDATE become …_MODIFY: a module or an automation that expected them no longer fires.
• 17: in computed extra fields, the current object is written $objectoffield. The hidden setting MAIN_LIST_ALLOW_NOTES becomes MAIN_LIST_HIDE_NOTES.
• 18: the version that broke the most external modules on our test bench (4 failures out of 6), because core methods changed shape. Sensitive keys on setup pages, such as API keys, are now encrypted in the database.
• 19: the official Docker images move from PHP 8.1 to PHP 8.2. In extra field conditions, the variables $soc and $right are no longer available.
• 20: filters of link-type extra fields must be written in the new universal filter syntax (field:=:value), no longer in SQL. A module that fills, entry by entry, an array it has not declared ($this->list['key'] = …) loses those values. This is not in the ChangeLog: found on our test bench, then reproduced.
• 21: the template variable __MEMBER_CIVILITY__ becomes __MEMBER_TITLE__. The PHP json extension becomes mandatory.
• 22: the hidden setting STOCK_ALLOW_NEGATIVE_TRANSFER is reversed and renamed STOCK_DISALLOW_NEGATIVE_TRANSFER. GETPOST is forbidden in extra field conditions.
• 23: $obj no longer works in computed fields and conditions; write $objectoffield, required since 17. The ChangeLog also announces the end of $object, but it still works in 23.0.4, 24.0.1 and 24.0.2: replace it now. Concatenation is disabled by default in computed fields.
• 24: the variable __MYCOUNTRY_ID__ disappears, replaced by __MYCOMPANY_COUNTRY_ID__. API login with username and password is off by default.
• 24, unalterable log trap (BlockedLog module), if you have used it since an old version: if its key was left in clear text in the database, no invoice can be validated any more in 24.0.0 or 24.0.1 (issue #40153). The error message then shows the key in clear text: do not share screenshots of it. 24.0.2, released on 2 October 2026 on SourceForge but not yet announced on dolibarr.org on 4 October, fixes this case. Tested: validation works again, and the key, unchanged, is re-encrypted at the first validated invoice. The upgrade wizard does not touch it. Until 24.0.2 is announced, have this point checked before moving to 24.

How this information was established

• PHP versions come from the installer of each version (install/check.php), not from the documentation, which sometimes differs.
• Removed modules come from comparing the core modules, version by version.
• Changes come from Dolibarr’s official ChangeLog.
• Failure figures come from 45 free modules really upgraded under Docker, with the official wizard, on the official Dolibarr 16 to 24 images.

This table will be kept up to date with each new version.

Getting help

If you would rather not run this operation on your invoicing tool yourself, that is exactly the Safe upgrade package: your instance is copied, the upgrade is rehearsed on the copy until it goes through, your invoices, PDFs and modules are checked, and only then do we switch over. If you first want to know where you stand, the €90 diagnosis reviews your version, your PHP and your modules, and its price is deducted from the package if you order it afterwards.

See also

• Back up and restore Dolibarr
• Dolibarr error 500 or blank page
• The install.lock file