How to Upgrade MediaWiki

When To Upgrade MediaWiki

The first step in upgrading your wiki, is to verify that you actually need to upgrade.

Start by checking your MediaWiki version by going to Special:Version. (Example URL: https://en.wikipedia.org/wiki/Special:Version)

To find out what the most recent version of MediaWiki is, check out the version lifecycle page on MediaWiki.org. This page lists the currently supported versions of MediaWiki, together with their release and End-of-life dates. For information on platform compatibility, such as supported versions of PHP, see the compatibility page.

Understanding MediaWiki Versions

MediaWiki unfortunately does not follow the Semantic Versioning standard. Even so, MediaWiki has both major and minor releases.

An example MediaWiki version is 1.39.2. There are 3 parts. The first part is always "1" and can be ignored. Some people in the community will simply call this example version MediaWiki 39.2 instead. The second part is the "39", and this is the major version. The final part, the "2", is the minor version.

Upgrading to a new major MediaWiki version is more difficult than upgrading to a new minor version.

Minor MediaWiki Versions

Minor version upgrade example: 1.39.2 => 1.39.3

Minor versions are mainly bug fixes including security fixes and the occasional feature.

When a new minor version is released for your major version of MediaWiki, it is important to upgrade in a timely manner. Not doing so can leave your wiki vulnerable due to unfixed security issues.

Luckily, these upgrades tend to be easy. You just replace the MediaWiki files. Database upgrades are not needed, and extensions do not need to be checked and upgraded along with MediaWiki itself.

Major MediaWiki Versions

Major version upgrade example: 1.38.4 => 1.39.0

Major versions are made twice a year, and contain all the changes made during the preceding 6 months. This includes big new features and breaking changes to existing features.

Upgrades of major versions are a lot more involved than for minor versions. You need to check that your MediaWiki extensions work with the new major version, that your platform has a supported version of PHP, and that features you depend on have not been removed or changed. Furthermore, you almost certainly will need to upgrade your wiki's database.

Unlike with minor versions, you do not always have to upgrade quickly when there is a new major MediaWiki version. Major MediaWiki versions are supported for one year, during which they will get security fixes in the form of minor versions. Every two years there is a Long Term Support (LTS) version, which is supported for 3 years. You can find the LTS MediaWiki versions on the version lifecycle page.

Before upgrading to a new major MediaWiki version, check the release notes. These will tell you what changed, and allow you to check if you need to migrate any configuration or wikitext.

Back Up MediaWiki

Making a backup of your wiki before you upgrade it is, of course, optional. However, we strongly recommend you make a backup if (1) you are new to MediaWiki upgrades, (2) you are upgrading a mission-critical wiki, or (3) you are upgrading to a new major version (which includes upgrading the database).

The easiest way to make a backup of your wiki is to make a snapshot of the entire VPS or server. This is possible on many hosts, and makes creating a backup, or restoring from a backup trivial. It saves you from dealing with MediaWiki specifics, and works regardless of how you installed and configured your wiki.

Unfortunately not all hosts allow you to create a server snapshot. A server snapshot is also not sufficient if your wiki database and upload storage are located elsewhere, such as on RDS and S3 for the more advanced AWS users.

If a server snapshot is not viable for your wiki, you will need to back up these things:

• Your wiki database
• Your wiki's upload storage
• Your LocalSettings.php configuration file

In most cases, you can make a backup of both the upload storage and of LocalSettings.php by making a copy of the entire MediaWiki installation directory. Doing so has the benefit that you also have a functional combination of wiki software to fall back to.

Back Up Your MediaWiki Database

For MySQL:

mysqldump --user=wiki_db_user --password=wiki_db_user_password wiki_db_name > backup.sql

For SQLite, run the following command in your MediaWiki root directory:

php maintenance/sqlite.php --backup-to backup

Get The Latest MediaWiki Version

In this step you replace your MediaWiki files with files from a new version.

You download MediaWiki via several routes. The most common ones are:

Option 1: Git Version Control

If you have MediaWiki installed via git, you can simply fetch the latest code, and check out the release tag of your choice. The tag matches the MediaWiki version.

git fetch -v --all
git checkout 1.38.4

Alternatively you can use the "release branch" of your major MediaWiki version. These branches follow the REL1_38 format and are listed on the release notes page. They allow you to get the latest fixes without waiting for minor releases to be made. You of course need to still do a git pull to get those fixes, and be a bit more careful than when using an official MediaWiki release.

git checkout REL1_38

Option 2: MediaWiki Tarball Download

You can download the tarball of the latest MediaWiki version on the download page. To download a specific version, check out the page dedicated to the major version in question. These pages are linked from the release notes page.

Option 3: Docker

If your wiki has been installed via Docker, you will need to get or build a new Docker image.

While you can roll your own Docker image, you can use the official MediaWiki images, either directly, or as foundation for your own image. Alternatively you can use the images published by Professional Wiki, which come with more modern PHP, extra packages and Lua.

If you roll your own image, you can get the desired MediaWiki version either via git or via tarball.

Upgrade Your MediaWiki Database

Once you upgraded your MediaWiki files, and possibly also the MediaWiki extensions you use, it is time to upgrade the wiki database.

SSH into your server and run the update.php script, which can be found in the maintenance directory.

php maintenance/update.php

Verify MediaWiki Upgrade Success

Visit the Special:Version page and verify that the expected version of MediaWiki is listed.

While most upgrading mistakes will cause Special:Version to fail, there are issues that will not show up just by visiting that page. Thus it is good to walk through the key functionality of your wiki, to make sure nothing is broken. A short version of such a check is making an edit to a page of your choice.

If you are running into problems, you can try finding help via the MediaWiki support desk. Another option is contracting the MediaWiki experts from Professional Wiki to upgrade your wiki.

Make Things Easy For Yourself

Save yourself time and headache by using the most modern MediaWiki hosting on the market.

With ProWiki you do not have to worry about upgrading MediaWiki. Upgrades happen automatically. You can configure your wiki via the admin panel UI, saving you from having to edit LocalSettings.php or run PHP scripts.

Create your wiki today via the free trial. Or contact us to migrate your wiki, possibly including a free MediaWiki upgrade.