How to Install MediaWiki Extensions Safely

MediaWiki extensions can add editors, authentication, anti-spam controls, semantic data and many other features. The important part is not just copying files into the server: you also need to confirm version compatibility, use the extension's own instructions, back up the wiki and run any required maintenance steps.

Before you install anything

1. Check your MediaWiki version. Open Special:Version in your wiki.
2. Read the extension page. Confirm that the extension supports your MediaWiki version and note any dependencies.
3. Back up first. Back up the database, LocalSettings.php, uploaded files and any custom configuration you would need to restore the site.
4. Use a staging copy for important wikis. An extension can conflict with another extension or with a newer MediaWiki release even when the installation itself is correct.

MediaWiki's official extension documentation specifically cautions that third-party extensions can be outdated, incompatible or insecure. Read the MediaWiki extension guidance.

Step 1: Get the extension from the recommended source

Start on the extension's page at MediaWiki.org and follow its installation instructions. Many extensions can be downloaded through MediaWiki's Extension Distributor; others use Git or Composer. Do not assume every extension is installed the same way.

If you download a package manually, keep the extension in its own directory under extensions/.

Step 2: Put the files in the extensions directory

A typical manual installation looks like this:

/path/to/mediawiki/extensions/ExtensionName/

The folder should contain the extension's files, including its registration file where applicable. Avoid leaving an extra nested directory created by an archive extraction, such as extensions/ExtensionName-1.2/ExtensionName/.

Step 3: Load the extension from LocalSettings.php

For modern extensions using MediaWiki's extension registration system, add the extension near the end of LocalSettings.php:

wfLoadExtension( 'ExtensionName' );

Some extensions require configuration lines after they are loaded. Use the exact settings shown in that extension's documentation rather than copying configuration from an old tutorial.

Step 4: Run a database update only when required

Extensions that add or change database tables may require MediaWiki's update maintenance script. On MediaWiki 1.40 and newer, the current command is:

php maintenance/run.php update

Older tutorials often show php maintenance/update.php. MediaWiki documents direct maintenance-script invocation as deprecated for current releases. Always make a database backup before running schema updates. See the official update.php documentation.

Step 5: Confirm the extension loaded

Open Special:Version and look under installed extensions. Then test the feature with an account that has the same permissions as the people who will actually use it.

If the wiki breaks after enabling an extension

1. Remove or comment out the new wfLoadExtension() line in LocalSettings.php.
2. Reload the site. If it returns, the failure is likely related to the extension, its configuration, a dependency or compatibility.
3. Check the web server/PHP error log instead of repeatedly changing settings at random.
4. Confirm the extension version matches your MediaWiki branch.
5. If you ran a schema update, follow the extension's documented rollback or restore procedure; do not assume deleting the extension folder reverses database changes.

Common mistakes

Updating extensions later

Keep extension updates tied to your MediaWiki upgrade process. MediaWiki's documentation recommends replacing the extension files with the appropriate newer version while keeping your configuration, then running the update script if the extension requires database changes. Test important extensions before upgrading a production wiki.

When self-hosting may be the wrong fit

If nobody on the team can maintain PHP, backups, updates and extension compatibility, a hosted documentation service may be a better operational choice even if its subscription costs more. See our hosted and self-hosted wiki comparison before committing to the server work.

Official source

This tutorial was checked against the current MediaWiki manuals in September 2026. Start with MediaWiki's extension installation and upgrade manual because individual extensions can require additional steps.