Updating
From the Admin Dashboard
If you have the extension manager extension installed you can simply run the update from its interface and skip this page entirely.
To update Flarum, you'll need to use Composer. If you're not familiar with it (although you should be, because you need it to install Flarum), read our guide for information on what it is and how to set it up.
If updating across major versions (e.g. <=0.1.0 to 1.x.x, 1.x.x to 2.x.x, ...), make sure to read the appropriate "major version update guide" before running the general upgrade steps.
General Steps
Step 1: Make sure all your extensions have versions compatible with the Flarum version you're trying to install. This is only needed across major versions (e.g. you probably don't need to check this if upgrading from v2.0.0 to v1.1.0, assuming your extensions follow recommended versioning). You can check this by looking at the extension's Discuss thread, searching for it on Packagist, or checking databases like Extiverse. You'll need to remove (not just disable) any incompatible extensions before updating. Please be patient with extension developers!
Step 2: Take a look at your composer.json file. Unless you have a reason to require specific versions of extensions or libraries, you should set the version string of everything except flarum/core to * (including flarum/tags, flarum/mentions, and other bundled extensions). Make sure flarum/core is NOT set to *. If you're targeting a specific version of Flarum, set flarum/core to that (e.g. "flarum/core": "v1.8). If you just want the most recent version, use "flarum/core": "^1.0".
Step 3: If your local install uses local extenders, make sure they are up to date with changes in Flarum.
Step 4: We recommend disabling third-party extensions in the admin dashboard before updating. This isn't strictly required, but will make debugging easier if you run into issues.
Step 5: Make sure your PHP version is supported by the version of Flarum you are trying to upgrade to, and that you are using Composer 2 (composer --version).
Step 6: Finally, to update, run:
composer update --prefer-dist --no-plugins --no-dev -a --with-all-dependencies
php flarum migrate
php flarum cache:clear
Step 7: If applicable, restart your PHP process and opcache.
Major Version Update Guides
Updating from v1 (^1.0.0) to v2 (^2.0.0)
- Do steps 1-5 above.
- Change the version strings of all bundled extensions (
flarum/tags,flarum/mentions,flarum/likes, etc) incomposer.jsonfrom^1.0(or^1.8, ...etc) to*. - Change
flarum/core's version string incomposer.jsonfrom^1.0(or^1.8, ...etc) to^2.0. - Preferably set the
"minimum-stability": "beta",line in yourcomposer.jsontostableunless you are still using a beta third party extension. - Do steps 6 and 7 above.
Troubleshooting Issues
There are 2 main places where you might run into errors when updating Flarum: while running the update command itself, or when accessing the forum after updating.
Errors While Updating
Here we'll go through several common types of issues while trying to update Flarum.
If the output is short and contains:
Nothing to modify in lock file
Or does not list flarum/core as an updated package, and you are not on the latest flarum version:
- Revisit step 2 above, make sure that all third party extensions have an asterisk for their version string.
- Make sure your
flarum/coreversion requirement isn't locked to a specific minor version (e.g.v1.8is locked,^2.0.0isn't). If you're trying to update across major versions of Flarum, follow the related major version update guide above.
For other errors, try running composer why-not flarum/core VERSION_YOU_WANT_TO_UPGRADE_TO
If the output looks something like this:
flarum/flarum - requires flarum/core (v0.1.0-beta.15)
fof/moderator-notes 0.4.4 requires flarum/core (>=0.1.0-beta.15 <0.1.0-beta.16)
jordanjay29/flarum-ext-summaries 0.3.2 requires flarum/core (>=0.1.0-beta.14 <0.1.0-beta.16)
flarum/core v0.1.0-beta.16 requires dflydev/fig-cookies (^3.0.0)
flarum/flarum - does not require dflydev/fig-cookies (but v2.0.3 is installed)
flarum/core v0.1.0-beta.16 requires franzl/whoops-middleware (^2.0.0)
flarum/flarum - does not require franzl/whoops-middleware (but 0.4.1 is installed)
flarum/core v0.1.0-beta.16 requires illuminate/bus (^8.0)
flarum/flarum - does not require illuminate/bus (but v6.20.19 is installed)
flarum/core v0.1.0-beta.16 requires illuminate/cache (^8.0)
flarum/flarum - does not require illuminate/cache (but v6.20.19 is installed)
flarum/core v0.1.0-beta.16 requires illuminate/config (^8.0)
flarum/flarum - does not require illuminate/config (but v6.20.19 is installed)
flarum/core v0.1.0-beta.16 requires illuminate/container (^8.0)
flarum/flarum - does not require illuminate/container (but v6.20.19 is installed)
flarum/core v0.1.0-beta.16 requires illuminate/contracts (^8.0)
flarum/flarum - does not require illuminate/contracts (but v6.20.19 is installed)
flarum/core v0.1.0-beta.16 requires illuminate/database (^8.0)
flarum/flarum - does not require illuminate/database (but v6.20.19 is installed)
flarum/core v0.1.0-beta.16 requires illuminate/events (^8.0)
flarum/flarum - does not require illuminate/events (but v6.20.19 is installed)
... (this'll go on for a bit)
It is very likely that some of your extensions have not yet been updated.
- Revisit step 1 again, make sure all your extensions have versions compatible with the core version you want to upgrade to. Remove any that don't.
- Make sure you're running
composer updatewith all the flags specified in the update step.
If none of this fixes your issue, feel free to reach out on our Support forum. Make sure to include the output of php flarum info and composer why-not flarum/core VERSION_YOU_WANT_TO_UPGRADE_TO.
Errors After Updating
If you are unable to access your forum after updating, follow our troubleshooting instructions.