Installing MediaWiki Extensions with Composer
Last updated on 2024-03-03. Written by Jeroen De Dauw
Nowadays many MediaWiki extensions can or should be installed via Composer. While this simplifies things once you know how it works, it also adds to the learning curve. This post covers the basics you need to know plus some tips that might be news to long time users.
This living article contains to the point and up-to-date instructions and is more comprehensive than the instructions specific to any extension. It is also a more understandable alternative to the instructions on MediaWiki.org.
What is Composer
Composer is tool for installing PHP packages. It can be used to install MediaWiki extensions and any PHP libraries required by those extensions. Composer also allows easy upgrading of extensions installed with it.
Modern versions of MediaWiki (1.25+) require using Composer during installation. So you most likely already have Composer installed. In that case you can skip the next section. If you are using an older version of MediaWiki or do not have console access then the instructions on this page won't work for you.
These instructions assume you have already set up MediaWiki and are using Linux. If you are using another operating system then installation of Composer and execution of commands can be slightly different.
You can install Composer globally with your package manager.
sudo apt install composer
Alternatively you can download the Composer executable. This is really simple and does not require sudo rights:
php composer.phar --version
For more details and ways to install Composer, see the Composer download instructions.
Installing extensions with Composer
There are 3 steps to installing MediaWiki extensions with Composer:
- Find the package names (and versions)
- Specify the package names (and versions)
- Run the update command
Note that some extensions require further setup unrelated to Composer. The most common case is the need to
run the MediaWiki
maintenance/update.php script that among other things creates database tables. This is
done after installation with Composer.
Step 1: Find the package names
Before you can specify which extensions to install, you need to find out what their Composer package names are.
Composer works with these package names. Examples are
mediawiki/maps for the
If the extension supports installation via Composer, its page on MediaWiki.org likely mentions it in the infobox
on the top right. Alternatively if you know where the source code of the extension is, you can look at the contents
composer.json file, which shows the package name at the top.
Packagist.org also provides a searchable list of MediaWiki extensions that can be installed via Composer.
Optional: once you have the package name you can view the package on
Packagist.org. The package page
will show you an always-up-to-date list of the extensions versions that you can install via Composer.
You can find the package name by using the search feature on Packagist or you can manually construct
the URL by adding the package name to the end of
Step 2: Specify the package names
Extensions to be installed (and managed by) Composer are specified in the
composer.local.json file located in the root directory of your MediaWiki.
You can look in this file to see which extensions are currently installed via Composer. Note that the file might not exist yet.
You can even edit the file directly if you are comfortable with editing JSON. Alternatively you can use the below command, which will edit the file for you, and create it if need be.
COMPOSER=composer.local.json composer require --no-update "mediawiki/maps:*"
This command needs to be run for each extension you want to install. Replace
with the package name of your extension.
"*" after the package name tells Composer to install the latest stable version of the extension.
It is good practice to specify the version. This makes upgrading safer. If you don't know the version or
do not want to be bothered to look it up, you can stick to using
COMPOSER=composer.local.json composer require --no-update "mediawiki/maps:~7.8"
This example will install the most recent Maps version equal to or more recent than 7.8 but lower than 8.0. This means you might get 7.8.1 or 7.9 but not 8.0 or anything 8.0+. The same will hold true for upgrading.
Step 3: Run the update command
The final step is to run the update command in the MediaWiki root directory. It will look like this:
composer update mediawiki/maps --no-dev -o
Remember that if you downloaded composer.phar, the command will start with
--no-dev option should be used unless you are working with a development with or otherwise
know what you are doing. Many extensions do not mention this flag in their installation instructions but
it is safe to add regardless.
-o flag adds an optimization steps to the installation process, enhancing performance of
If you added multiple new extensions, you can install all of them in one go by not specifying the package name. Note that this will also upgrade extensions that are already installed.
composer update --no-dev -o
To see what will happen before you run the update command, run it with the
composer update --no-dev -o --dry-run
Step 4: Enable the extensions
Many extensions require an extra step to be enabled after they are installed. This is typically
done via a call to
wfLoadExtension() in your
Please refer to the installation instructions for the individual extension and to the
extension registration documentation.
To see if an extension is enabled, check the
Special:Version page of your wiki.
To upgrade extensions already installed with Composer you need the same command as for installation.
composer update --no-dev -o
While this command can upgrade all extensions, you do have control over which ones get upgraded and
to which versions. This is where the versions in
composer.local.json come into play.
There are three types of constraints commonly used on production wikis. You can choose between those for extensions individually and you can change the constraints over time as you see fit.
The types of constraints are:
- No versions with breaking changes, but new features and bug fixes are OK
- No versions with breaking changes, but bug fixes are OK
- Only this specific version
The first constraint is the most common and what we recommend to use in case of doubt.
If you use any of these constraints Composer will not pull in breaking changes.
This is done via the magic of Semantic Versioning.
It also means that if you want a new major version of an extension (ie version 5 instead of version 4),
you'll need to explicitly update the number in
Both during installation and upgrades Composer takes care of not installing versions it knows will not work on your system. This means you do not need to worry about PHP versions. Composer will either install the most recent version that works on your system or tell you there is no such version.
Constraint 1: new features and bug fixes
To only get bug fix releases when upgrading, prefix the version with a tilde:
Important: the version should have two parts. So
16.35 are both fine,
1 are not.
This example will install the most recent Maps version equal to or more recent than 7.8 but lower than 8.0. This means you might get 7.8.1 or 7.9 but not 8.0 or anything 8.0+.
Constraint 2: Bug fixes only
To only get bug fix releases when upgrading, specify three part versions and prefix them with a tilde:
COMPOSER=composer.local.json composer require --no-update "mediawiki/maps:~7.8.2"
Important: the version should have three parts. So
23.34.42 are both fine,
1.23 are not.
When upgrading you will get the most recent
7.8.x release equal to or higher than
Constraint 3: Fixed versions
If you do not want ANY updates to happen to an extension, just specify its full version number during installation.
If you then run the update command, the extension will not be upgraded. It's possible to then change the
composer.local.json and run the update command to upgrade to that exact version.
COMPOSER=composer.local.json composer require --no-update "mediawiki/maps:7.8.2"
Having problems setting up or upgrading your wiki? We provide professional support. Or avoid dealing with Composer and other technicalities altogether by using one of our fully managed MediaWiki hosting plans.
- New extension: Wikibase Export
- Semantic MediaWiki 4.1.0 released
- Embedding External Content in MediaWiki
- SMWCon 2021
- WikidataCon 2021
- Best Responsive MediaWiki Skins
- Medik MediaWiki Skin
- Happy 20th Anniversary Wikipedia
- Semantic MediaWiki 3.2
- Local Media Support for Wikibase
- Chameleon MediaWiki Skin
- Foreground MediaWiki Skin
- Pivot MediaWiki Skin
- Tweeki MediaWiki Skin
- Semantic Wikibase Released
- Visualizing Links Between Pages
- MediaWiki Survey
- SMW vs Wikibase vs Cargo
- Using Wikidata in Your Wiki
- Visual Map Editor for MediaWiki
- WikidataCon 2019 Berlin
- Installing Extensions with Composer
- SMWCon 2019 Paris