Skip to main content
Version: 2.x

Updating

danger

Flarum 2.0 is currently in beta. It is not ready for production use. Please wait for the stable release before updating your forum.

From the Admin Dashboard​

info

If you have the extension manager extension installed you can simply run the update from its interface and skip the general steps. You should still read the "Major Version Update Guide" if you are updating from v1 to v2.

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)​

  1. If you are using a MariaDB database, you should change the driver in config.php from mysql to mariadb:
     <?php return array (
       'debug' => true,
       'offline' => false,
       'database' =>
       array (
         'driver' => 'mysql',
         'driver' => 'mariadb',
         'host' => 'localhost',
         'port' => 3306,
  2. Do steps 1-5 above.
  3. Change the version strings of all bundled extensions (flarum/tags, flarum/mentions, flarum/likes, etc) in composer.json from ^1.0 (or ^1.8, ...etc) to *.
  4. Change flarum/core's version string in composer.json from ^1.0 (or ^1.8, ...etc) to ^2.0.
  5. Preferably set the "minimum-stability": "beta", line in your composer.json to stable unless you are still using a beta third party extension.
  6. 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/core version requirement isn't locked to a specific minor version (e.g. v1.8 is locked, ^2.0.0 isn'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 update with 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.