In this article you will learn how to quickly and safely upgrade MediaWiki.
Once you determined that your wiki needs to be upgraded, follow these steps:
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
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.
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.
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.