How To Customize MediaWiki Using the LocalSettings.php File

Published on September 16, 2013
How To Customize MediaWiki Using the LocalSettings.php File


MediaWiki is an open source wiki application that allows you to create your customizable wiki sites. Originally developed by the WikiMedia Foundation to serve the needs of Wikipedia, it can be adapted for individuals and smaller organizations.

This guide assumes that you have installed MediaWiki on your VPS and have completed the initial configuration steps with your web browser. If this is not the case, please follow the instructions here to install MediaWiki.

In a previous guide, we installed MediaWiki on an Ubuntu 12.04 installation. In this article, we will go over some basic configuration that can be done through the LocalSettings.php file.

Can You Edit Preferences Through the Web Interface?

Although many preference changes and site management tasks can be administered through the normal wiki web interface, there are some changes that require editing text files on the server.

The LocalSettings.php file is not accessible from the web interface as a security measure. To edit the file, SSH into your VPS in order to edit this file manually.

Where Does MediaWiki Store Default Values?

Default settings are kept in a file called DefaultSettings.php.

You should never edit DefaultSettings.php, but looking at it can be very valuable. Since we will not edit the file, open it in a pager:

less /etc/mediawiki/includes/DefaultSettings.php

If you see a value in this file that you wish to change, take note of it. Later, you can add the value to the LocalSettings.php file.

How Do You Edit Default Values?

Configuration should be done in the LocalSettings.php file. It looks very similar to DefaultSettings.php, but is shorter. Type the following command to open the file for editing:

sudo nano /etc/mediawiki/LocalSettings.php

This file is written in the PHP programming language, but the syntax is relatively easy to understand. For the most part, you will see the following syntax:

<pre> $<span class=“highlight”>VariableName</span> = “<span class=“highlight”>VariableValue</span>”; </pre>

This file has many different configuration settings, but not all of the available settings are defined here. Generally, only those settings with values that contradict the defaults found in DefaultSettings.php are found here.

If you wish to change the settings of anything found in DefaultSettings.php, look for the variable in LocalSettings.php. If it does not exist, add it to the bottom.

Common Configuration Settings

Before making any changes, go ahead and backup the configuration file in case something does not work as expected:

sudo cp /etc/mediawiki/LocalSettings.php /etc/mediawiki/LocalSettings.php.bak

Reopen the LocalSettings.php file to edit the following values.

sudo nano /etc/mediawiki/LocalSettings.php

How To Change the Site Name

You selected a name for your site during initial configuration. You can change your site’s name by editing two variables: wgSitename and wgMetaNamespace.

<pre> $wgSitename = “<span class=“highlight”>New Site Name</span>”; $wgMetaNamespace = “<span class=“highlight”>New_Site_Name</span>”; </pre>

The second variable sets namespace for the pages that refer to the wiki itself. It cannot contain spaces, so we use underscores instead.

How To Change the Site Language

If you need to change the language encoding of your site, you can modify the value of the wgLanguageCode variable:

<pre> $wgLanguageCode = “<span class=“highlight”>language_code</span>”; </pre>

The “language_code” in this instance refers to any value defined in this file:

less /etc/mediawiki/languages/Names.php

After changing the language, you need to run a script to implement the change:

cd /etc/mediawiki/maintenance
sudo php rebuildmessages.php --rebuild

How To Allow Image Uploads

Before we allow image uploading on the wiki, we want to install some additional image-handling software from the “imagemagick” suite:

sudo apt-get install imagemagick

Reopen the LocalSettings.php file.

sudo nano /etc/mediawiki/LocalSettings.php

To allow your wiki’s users to upload their own images to pages, you can change the wgEnableUploads variable to “true”:

$wgEnableUploads = true;

Uncomment the next two variables to configure MediaWiki to use imagemagick for image resizing, converting, and manipulating.

$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";

These settings will enable the ability to use thumbnail images for user uploads.

By default, these settings allow for uploads in “png”, “gif”, and “jpeg/jpg” formats. If you would like to allow additional formats, add the wgFileExtensions variable to the bottom of the file like so:

<pre> $wgFileExtensions = array( ‘png’, ‘gif’, ‘jpg’, ‘jpeg’, ‘<span class=“highlight”>pdf</span>’, ‘<span class=“highlight”>additional_format</span>’, ‘<span class=“highlight”>…</span>’) </pre>

Note: Any website that accepts content from users is adopting a certain level of risk! Be sure that you are aware of the implications of allowing user uploads and take the appropriate steps to mitigate these dangers.

How To Allow WikiCommons Images

An additional variable that you may wish to set to “true” is wgUseInstantCommons.

This allows your wiki to automatically configure access to content in Wikimedia Commons. These can be incorporated into your own pages.

$wgUseInstantCommons = true;

To use images from Wikimedia Commons, find an image you’d like to use at:


Navigate to your image. In the URL, copy from File: to the end of the URL.

<img style=“border:2px solid black; display:block;margin-left:auto;margin-right:auto” src=“https://assets.digitalocean.com/articles/mediawiki_config/wikimedia_url.png” alt =“MediaWiki File URL” />

Now, open or edit a page, and simply paste what you’ve copied within double brackets


The image will be available on your page.

If you wish to make a thumbnail instead, follow the filename with a pipe character (|) and “thumb”.


The WikiMedia image will show up on your wiki:

<img style=“border:2px solid black; display:block;margin-left:auto;margin-right:auto” src=“https://assets.digitalocean.com/articles/mediawiki_config/commons_image.png” alt =“MediaWiki Commons example image” />

One commonly requested piece of information is how to change the logo in the upper-left corner of the page to something relevant to your site.

By default, the wiki page displays the following image:

<img style=“border:2px solid black; display:block;margin-left:auto;margin-right:auto” src=“https://assets.digitalocean.com/articles/mediawiki_config/default_logo.png” alt =“MediaWiki Default Logo” />

First, copy the file you want to act as your logo into the appropriate directory on your VPS:

<pre> scp <span class=“highlight”>/path/to/local/image.png</span> <span class=“highlight”>username</span>@<span class=“highlight”>server_ip</span>:/etc/mediawiki/skins/common/images/ </pre>

Now you have the image on your wiki server. Change the path of wgLogo to reflect the image name:

<pre> $wgLogo = "$wgStylePath/common/images/<span class=“highlight”>image_name.png</span> </pre>

Your logo will now replace the former message.

How To Configure Email Options

To receive administrative emails, including bug reports, include your email after the wgEmergencyContact variable.

<pre> $wgEmergencyContact = “<span class=“highlight”>your_email@address.com</span>” </pre>

You will also want to configure the wgPasswordSender email to point to an actual email address, so that users can respond to the email if they have problems.

<pre> $wgPasswordSender = “<span class=“highlight”>password_email@address.com</span>” </pre>


You should now know how to configure some common settings located within the LocalSettings.php file.

There are many, many configuration settings available for MediaWiki that are not present in LocalSettings.php by default. Remember to read the default settings file located at /etc/mediawiki/includes/DefaultSettings.php to discover more configuration options. The file is well-commented. More information on specific variables can be found here.

<div class=“author”>By Justin Ellingwood</div>

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us

About the authors

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

This doesn’t work for me.

sudo nano /etc/mediawiki/LocalSettings.php

Opens a blank file. Where is this file located after using the one click install?

Hi! I’m trying to install the Google analytics extension for my wiki. I successfully inserted the require_once needed in LocalSettings.php but I don’t know how to upload the files I need in a directory called googleAnalytics in my extensions/ folder.

Do I need to create this directory first? If not, how can I access it from the console?

Additionally, how do I upload these files?!

How do I access the LocalSettings.php file? Is it different if I hosted with HostGator?

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel