How to Download and Install MediaWiki Extensions

Introduction

As a long-time MediaWiki developer and power-user, you know that one of the strengths of MediaWiki is the ecosystem of extensions hosted on MediaWiki.org.

These extensions can add a wealth of functionality: parser functions, widgets, special pages, API modules, or even whole new workflow tools.

But even seasoned developers sometimes slip when installing, upgrading, or uninstalling them. In this post I’ll walk through best practices and pitfalls when bringing extensions from MediaWiki.org into your MediaWiki instance.

1. Before You Start

• Find out which version(s) of MediaWiki you are running, and whether the extension supports that version. The infobox on the MediaWiki.org extension page will usually say “MediaWiki X.Y+” for minimal version.
• Make sure you have necessary access: shell (SSH) and file system access to the server (so you can place files, adjust permissions, etc.). Without that, some things may break or become cumbersome.
• If the extension has dependencies (other extensions, or specific PHP modules, or if you must run Composer), read its README/documentation carefully. Sometimes there are database schema changes involved.

2. Locating the Extension You Want

You’ll usually find extensions in a few places:

• MediaWiki’s Extensions directory on MediaWiki.org (browse “All extensions” or by category) to see what’s available.
• The extension’s own page will often list download options: Git repository clone URLs, tar/zips, Composer-compatible packages.
• If you plan to maintain multiple extensions, you may favor using Git or Composer for easier versioning.

3. Downloading the Extension

Once you’ve picked an extension:

• Either clone the Git repository into your local extensions/ExtensionName directory.
• Or download a zip/tarball release and extract it into extensions/ExtensionName.
• If the extension declares a Composer package and your MediaWiki setup uses Composer, you may prefer installing the extension via Composer instead.

Ensure that after extraction or clone, the directory structure matches what the extension expects (often extensions/WidgetName/…, with subdirectories includes/, resources/, etc.). Check the README or extension.json.

4. Installing / Enabling the Extension

After files are in place, open your LocalSettings.php file (in the root of your wiki installation). Add the loading call (usually near the end of the file):

wfLoadExtension( 'ExtensionName' );

Then follow these steps:

• If the extension needs configuration, add configuration variables after you call wfLoadExtension(), so your settings will override defaults.
• Be aware of directory permissions: the web server needs read (and sometimes write) permissions on the extension directory and any folders it uses (caches, compiled templates, etc.).

If the extension suggests using conditional loading (for example to avoid breaking maintenance scripts), you can wrap the wfLoadExtension( 'ExtensionName' ) call in a check like:

if ( ! $wgCommandLineMode ) {
    wfLoadExtension( 'ExtensionName' );
}

5. Running Any Required Maintenance or Configuration Steps

Some extensions require more than just enabling:

• If they add database tables or change schema, you’ll need to run update.php from the command line (MediaWiki’s maintenance script). Always back up your database before running it.
• Some extensions require Composer-installed dependencies. If you installed via Composer, make sure to run composer update or the appropriate command.
• Adjust any settings in LocalSettings.php (namespaces, permissions, etc.) according to the extension’s documentation.

6. Testing the Extension

Once the extension is loaded:

• Clear caches / purge pages so that recent changes take effect.
• Navigate to Special:Version on your wiki to confirm the extension shows up as installed.
• Test functionality of the extension: special pages, parser functions, widgets, etc. If errors or blank pages arise, check error logs (PHP / web server).

7. Upgrading an Extension

Over time you’ll want newer versions of extensions:

• Download the newer release, or update via Git or Composer if used. Replace the files in extensions/ExtensionName with the new version.
• Do not remove or alter the wfLoadExtension(...) line or your configuration in LocalSettings.php.
• If the new version posts database changes, run update.php (or use web updater if CLI access isn’t available). Always back up first.

8. Uninstalling Extensions

If you no longer need an extension:

• Remove (or comment out) the wfLoadExtension('ExtensionName') line (and any related configuration) from LocalSettings.php.
• Optionally, remove the extension’s files from extensions/ExtensionName to declutter.
• If the extension made database changes or added tables, you may need to manually clean those up (if the extension provides scripts or documentation for uninstalling, follow that).

9. Using Advanced or Alternative Installation Options

Some situations call for more advanced setups:

• Custom locations: If you don’t want to use the $IP/extensions directory, you can adjust $wgExtensionDirectory, or use the second parameter of wfLoadExtension() to specify a custom path.
• Composer-based installation: increasingly many extensions support this; it's a cleaner dependency management approach, especially in development or large deployments.

Batch loading: When you have many extensions, instead of many wfLoadExtension() calls, you can use:

wfLoadExtensions( [ 'ExtA', 'ExtB', 'ExtC' ] );

Note limitations: you can’t specify custom paths in that form.

10. Common Pitfalls and Troubleshooting Tips

• Version mismatch: Using an extension version incompatible with your MediaWiki version can break functionality (or worse, security). Always check compatibility.
• Wrong permissions: Failed writes or lack of access to cache/compiled dirs often cause silent failures or error logs.
• Dependencies missing: e.g. missing PHP modules, or expecting other MediaWiki extensions.
• Caching issues: old static cached files, or browser caching confused by CSS/JS changes in extension resources.
• Maintenance script breaks: some extensions access superglobals or expect web context; wrapping load calls in if ( ! $wgCommandLineMode ) can mitigate issues when running update.php etc.

Conclusion

Installing MediaWiki extensions is one of the most powerful ways to extend your wiki installation, but doing it properly saves you from version drifts, security issues, or painful upkeep. By following the process—check compatibility, download properly, enable cleanly, configure, test, and maintain/upgrade/uninstall carefully—you’ll have a stable, feature-rich wiki setup.