MediaWiki File Upload Management Guide

File uploads are disabled by default in MediaWiki. This is a deliberate security decision, documented in MediaWiki's official configuration manual, and it means that enabling uploads on a new installation requires an explicit set of configuration steps rather than just flipping a switch.

Getting uploads right involves more than enabling them. The allowed file types, file size limits, upload directory security, and user permissions all affect whether uploads are safe, functional, and manageable over time. A wiki that allows uploads without restricting script execution in the uploads directory has a known security vulnerability. A wiki configured with PHP-level size limits that contradict the MediaWiki-level limits will produce confusing errors for users. These are avoidable problems with straightforward solutions.

This guide covers the complete upload configuration process in the order it should be done, plus day-to-day file management, troubleshooting, and the security considerations specific to file uploads.

For the upload directory security hardening that should accompany any upload configuration, the foundational steps are also covered in "MediaWiki Security Hardening Guide".

How MediaWiki File Uploads Work

When a user uploads a file via Special:Upload, MediaWiki carries out several checks before accepting it:

1. The user's account must hold the upload permission (granted to registered users by default, not to anonymous visitors).
2. The file extension must be in the list of allowed extensions defined by $wgFileExtensions, and must not appear in $wgProhibitedFileExtensions.
3. If $wgVerifyMimeType is enabled (the default), MediaWiki checks that the file's actual MIME type matches its declared extension - this catches attempts to disguise a dangerous file type as a benign one.
4. The file size must be within the limit set by both PHP's hard limit (upload_max_filesize in php.ini) and MediaWiki's own limit ($wgMaxUploadSize).

If all checks pass, the file is stored in the upload directory (by default the images/ subdirectory of the MediaWiki installation), a page is created in the File namespace documenting the upload, and the file is available for use in wiki pages.

Uploaded files are stored under the images/ directory in a hashed subdirectory structure by default - for example, a file named diagram.png might be stored at images/a/ab/diagram.png. This structure (controlled by $wgHashedUploadDirectory, which defaults to true) distributes files across subdirectories to avoid performance problems on filesystems that handle large numbers of files in a single directory poorly.

Step 1: Verify the PHP Configuration

Before enabling uploads in MediaWiki, confirm that PHP itself permits file uploads. The file_uploads directive in php.ini must be set to On. On most standard server configurations this is the default, but it is worth verifying before proceeding.

Check the current value:

php -i | grep file_uploads

If it shows file_uploads => Off, open the active php.ini file:

php -i | grep "Loaded Configuration File"

Then edit the file and set:

file_uploads = On

While in php.ini, also note the current values of upload_max_filesize and post_max_size - these are PHP-level hard limits that cannot be overridden by MediaWiki settings and must be set here if larger uploads are needed. The default values are typically 2 MB and 8 MB respectively, which are too small for most business wikis that accept document uploads.

Set an appropriate upload size limit for individual files:

upload_max_filesize = 50M

Set the post size limit to at least equal to or greater than upload_max_filesize:

post_max_size = 55M

Restart Apache after changing php.ini:

sudo systemctl restart apache2

Step 2: Enable Uploads in LocalSettings.php

With PHP configured to permit uploads, enable them in MediaWiki. Open LocalSettings.php and add:

$wgEnableUploads = true;

This is the only line strictly required to enable the upload system. Everything else in this guide refines what is allowed, how large files can be, and who can upload - but this single setting is the gate.

MediaWiki's official documentation notes that $wgEnableUploads should be added after other upload-related settings in LocalSettings.php, not before them, to ensure the configuration initialises in the correct order.

Step 3: Configure Allowed File Types

MediaWiki's default allowed file extensions are a minimal set of image formats:

// Default extensions (do not paste this line; it shows the default only)
// 'png', 'gif', 'jpg', 'jpeg', 'webp'

For a business wiki that needs to host PDFs, Office documents, and other file types, the allowed list needs to be extended. The recommended approach is to append to the existing default array using the array_merge function, rather than overriding the whole array - this preserves any new default extensions added by future MediaWiki upgrades:

$wgFileExtensions = array_merge( $wgFileExtensions, [ 'pdf' ] );

$wgFileExtensions = array_merge( $wgFileExtensions, [ 'docx', 'xlsx', 'pptx' ] );

$wgFileExtensions = array_merge( $wgFileExtensions, [ 'odt', 'ods', 'odp' ] );

To add a single extension at a time:

$wgFileExtensions[] = 'pdf';

$wgFileExtensions[] = 'docx';

$wgFileExtensions[] = 'mp4';

Prohibited extensions. Certain file types are hardcoded as prohibited in MediaWiki regardless of what is in $wgFileExtensions, because they pose serious security risks if served from a web server. These include executable types such as exe, php, js, html, and several others. These are controlled by $wgProhibitedFileExtensions. MediaWiki's documentation strongly advises against removing entries from this list.

A note on SVG. SVG is a vector image format that is structurally similar to HTML and can contain embedded scripts. MediaWiki checks SVG uploads for security, but its own security manual explicitly states that SVG files present additional risk and recommends serving uploaded files from an entirely separate domain - not just a subdomain - as a defence-in-depth measure specifically when SVG uploads are permitted.

Step 4: Set File Size Limits

MediaWiki has its own configurable upload size limit that operates alongside PHP's hard limit. The MediaWiki limit defaults to 100 MB but is constrained by the lower of the two values - if PHP's upload_max_filesize is set to 50 MB, MediaWiki's 100 MB limit has no effect because PHP will reject the file first.

Set the MediaWiki-level maximum upload size:

$wgMaxUploadSize = 1024 * 1024 * 50;

This sets the limit to 50 MB (expressed in bytes). The value must be equal to or lower than upload_max_filesize in php.ini to be effective.

Optionally, set a soft warning threshold that alerts the user without blocking the upload:

$wgUploadSizeWarning = 1024 * 1024 * 10;

This warns users if they attempt to upload a file larger than 10 MB, prompting them to consider whether a smaller version would be appropriate, while still allowing the upload to proceed up to the hard limit.

Step 5: Secure the Upload Directory

This is the most security-critical step in upload configuration. If PHP script execution is not disabled within the upload directory, an attacker who successfully uploads a PHP file (by bypassing extension checks) could execute it by requesting the URL directly, compromising the server.

For Apache, create or confirm that an .htaccess file exists in the images/ directory with the following content:

sudo nano /var/www/html/w/images/.htaccess

Add the directive to disable PHP processing:

php_admin_flag engine off

For additional defence, prevent the browser from treating uploaded HTML-like files as executable:

AddType text/plain .html .htm .shtml .phtml

For Nginx, add the following inside the server block:

location ~* ^/images/.*\.(php|pl|py|cgi|sh)$ {
    return 403;
}

Also confirm the upload directory is owned by the web server user and writable only by that user:

sudo chown -R www-data:www-data /var/www/html/w/images

sudo chmod 755 /var/www/html/w/images

MediaWiki's installer will display a warning if it detects that the images directory is vulnerable to script execution. If this warning appeared at installation and was not addressed, addressing it now before enabling uploads is essential.

Step 6: Configure User Permissions for Uploads

By default, any registered user can upload files once uploads are enabled. Anonymous users cannot. This default is appropriate for most wikis but can be adjusted.

To restrict uploads to a specific user group only - for example, only administrators:

$wgGroupPermissions['*']['upload'] = false;

$wgGroupPermissions['user']['upload'] = false;

$wgGroupPermissions['sysop']['upload'] = true;

To allow uploads by a custom group (for example, a group named editors):

$wgGroupPermissions['editors']['upload'] = true;

To re-enable uploads for all registered users after restricting them:

$wgGroupPermissions['user']['upload'] = true;

To allow uploading of files that overwrite existing ones (a separate permission from basic upload):

$wgGroupPermissions['user']['reupload'] = true;

$wgGroupPermissions['user']['reupload-shared'] = true;

Configuration Reference

Key MediaWiki File Upload Configuration Variables

Variable	Purpose	Default
$wgEnableUploads	Master switch to enable or disable the file upload system	false (disabled by default)
$wgFileExtensions	Array of allowed file extensions	[ 'png', 'gif', 'jpg', 'jpeg', 'webp' ]
$wgProhibitedFileExtensions	Extensions that can never be uploaded, regardless of $wgFileExtensions	Long list of executable and dangerous types
$wgStrictFileExtensions	If true, blocks uploads of extensions not in $wgFileExtensions; if false, only warns	true
$wgVerifyMimeType	Verifies the file's actual MIME type matches its extension	true - do not disable
$wgMaxUploadSize	Maximum file size in bytes MediaWiki will accept	100 MB (subject to PHP hard limit)
$wgUploadSizeWarning	File size in bytes at which MediaWiki warns the uploader (upload still permitted)	Not set by default
$wgUploadDirectory	Filesystem path where uploaded files are stored	/path/to/wiki/images
$wgUploadPath	Web-accessible URL path to the upload directory	/w/images (or equivalent)
$wgHashedUploadDirectory	If true, files stored in subdirectories based on MD5 hash for filesystem performance	true

Step 7: Using Uploaded Files in Wiki Pages

Once a file is uploaded, it is available in the File namespace (e.g. File:Diagram.png) and can be embedded in any wiki page using wikitext syntax.

Display an image with a caption:

[[File:Diagram.png|thumb|Caption text here]]

Display an image at a specific width:

[[File:Diagram.png|300px|alt=Description of image]]

Link directly to a file for download rather than displaying it inline:

[[Media:Report.pdf|Download the report]]

Display an image with no border or frame, placed inline:

[[File:Logo.png|frameless|40px]]

The thumb parameter generates a thumbnail using ImageMagick (if enabled) or GD, and links the thumbnail to the full file page. The alt parameter provides alternative text for accessibility and should be used on all meaningful images.

Step 8: Managing Uploaded Files

Viewing all uploaded files. Special:ListFiles displays all files uploaded to the wiki, sortable by uploader, date, and file name.

Viewing file details. Each uploaded file has a dedicated File page (e.g. File:Diagram.png) that shows the file itself, its upload history, metadata, and a list of all pages that use it. This "file usage" list is built from the imagelinks table and updated by the refreshLinks maintenance script.

Deleting files. Administrators can delete a file from its File page using the standard delete action. Deletion moves the file to the filearchive table in the database and removes it from the images directory. Deleted files can be restored by an administrator via Special:Undelete.

Re-uploading files. Uploading a new version of an existing file by using the same filename creates a new entry in the file's upload history. The previous version remains accessible from the File page's history section and can be restored if needed.

Moving or renaming files. Files can be renamed using the standard page move function, accessible from the File page. Renaming a file updates the File namespace page but does not automatically update links to the old filename in existing pages - this requires running the refreshLinks maintenance script or manually updating affected pages.

Finding unused files. Special:UnusedFiles lists uploaded files that are not currently embedded in any page. This is a useful starting point for periodic media audits.

Checking duplicate files. Special:FileDuplicateSearch identifies files that are identical in content (same MD5 hash) but uploaded under different filenames.

Best Practices

Always secure the upload directory before enabling uploads - addressing this as a retrofit after the wiki is already running with uploads enabled is possible but means there has been a window of vulnerability. Keep $wgVerifyMimeType at its default value of true; disabling it removes a meaningful layer of defence against disguised file types and is not justified for production wikis. Use array_merge to extend the allowed extensions list rather than overriding $wgFileExtensions entirely, since overriding the default array prevents MediaWiki from adding new safe defaults in future releases. Set PHP's upload_max_filesize and post_max_size to reasonable values before deployment and document them for editors, since confusing errors appear when users hit PHP-level limits without being told why. Conduct periodic audits of Special:UnusedFiles to keep the upload directory from accumulating orphaned files that take up storage but are not used anywhere. Include the images/ directory in regular file system backups - the database backup preserves file metadata, but the actual uploaded files live only on the file system.

Common Mistakes

Enabling uploads without first securing the upload directory against script execution is the most serious recurring mistake - the MediaWiki installer explicitly warns about this, and the warning should always be resolved before enabling uploads rather than deferred. Setting $wgMaxUploadSize to a large value without also adjusting PHP's upload_max_filesize and post_max_size leads to confusing failures where uploads above PHP's hard limit are rejected with a generic server error rather than a clear message about file size. Disabling $wgVerifyMimeType or $wgStrictFileExtensions to work around upload errors without investigating the actual cause weakens the upload validation chain without solving the underlying issue. Allowing SVG uploads without understanding the associated security considerations - and without the upload directory security measures already in place - introduces a specific risk that standard image formats do not. And not including the images/ directory in file system backups is a common oversight that only becomes apparent when a restore is needed and uploaded files are found to be unrecoverable.

Troubleshooting Common Upload Errors

Common MediaWiki Upload Errors and Fixes

Error Message	Likely Cause	Fix
"File upload is disabled"	$wgEnableUploads not set to true, or PHP's file_uploads is Off	grep file_uploads
"The file you uploaded seems to be empty"	PHP's post_max_size is smaller than the uploaded file size, causing PHP to silently discard the body	Increase post_max_size in php.ini to at least equal upload_max_filesize
"[Extension] is not a recommended image file format"	File extension is not in $wgFileExtensions	Add the extension to the allowed list using $wgFileExtensions[] = 'ext';
"The file is corrupt or has an incorrect extension"	MIME type of the uploaded file does not match its extension, often occurs with OpenDocument files	Some formats (ODF, for example) use MIME types that don't match their extension cleanly; consult MediaWiki's documentation for the specific type
Upload succeeds but file does not display	Images directory not writable by the web server, or $wgUploadPath and $wgUploadDirectory are not aligned	Confirm www-data owns the images directory; confirm both path settings point to the same location
"You do not have permission to upload files"	The user's account does not hold the upload permission	Check $wgGroupPermissions in LocalSettings.php; confirm the user is in a group with upload rights
Large file uploads silently fail at a specific size	PHP-level size limits are too low	Increase upload_max_filesize and post_max_size in php.ini; restart Apache

Frequently Asked Questions

Why are uploads disabled by default in MediaWiki?

MediaWiki's official documentation states that uploads are disabled by default as a security measure, since enabling them without the accompanying security configuration - particularly disabling script execution in the upload directory - creates a known server vulnerability. The default-off approach ensures administrators make an explicit, informed choice to enable uploads rather than having them active unintentionally.

How do I allow PDF uploads specifically?

Add $wgFileExtensions[] = 'pdf'; to LocalSettings.php. PDFs are not in the default allowed list but are not in the prohibited list either, so this single line is sufficient to enable them.

Can I change the directory where uploaded files are stored?

Yes, using $wgUploadDirectory and $wgUploadPath. MediaWiki's official documentation warns that both variables must be updated together and must be consistent with each other - if they point to different locations, files will be stored in one place but MediaWiki will look for them in another.

How do I increase the maximum upload file size?

Two settings must both be updated. In php.ini, increase upload_max_filesize and post_max_size. Then in LocalSettings.php, update $wgMaxUploadSize. The effective limit is whichever value is lower. Restart Apache after changing php.ini.

What happens to deleted files?

Deleting a file from its File page moves its metadata to the filearchive database table and removes it from the images directory. Administrators can restore deleted files via Special:Undelete as long as the database has not been manually purged.

Is it safe to allow SVG uploads?

With caution. SVG files can contain embedded scripts and are structurally similar to HTML, making them a higher-risk upload type than standard image formats. MediaWiki performs security checks on SVG uploads, but its own security documentation specifically recommends serving uploaded files from a separate domain when SVG uploads are permitted, as a defence-in-depth measure.

Can anonymous users upload files?

No, by default. Anonymous visitors do not hold the upload permission in MediaWiki's default group permissions. Files can only be uploaded by registered, logged-in users. This default should not be changed unless there is a specific, considered reason to allow it.

Conclusion

MediaWiki's file upload system is deliberately conservative by default - uploads are disabled, and the allowed file types are intentionally minimal. This reflects a considered trade-off: enabling uploads without addressing security configuration introduces real risk, so the defaults require an administrator to make an explicit, informed decision to enable them.

The configuration steps in this guide follow the order that MediaWiki's own documentation recommends: confirm PHP settings first, then enable uploads, extend the allowed types to match actual requirements, set appropriate size limits, secure the upload directory, and configure permissions. Each step builds on the previous one, and the security hardening step - disabling script execution in the images directory - is the one that should not be deferred.

Day-to-day file management, once the system is configured correctly, is straightforward. The File namespace, Special:ListFiles, Special:UnusedFiles, and the file history on each File page provide the tools needed to keep uploaded media organised and auditable over time.

For help configuring file uploads as part of a new wiki deployment or reviewing the security of an existing installation, see SolidWiki's MediaWiki Development Services page.

See Also

• MediaWiki Security Hardening Guide
• How to Install MediaWiki on Ubuntu Server
• MediaWiki Namespaces Explained
• MediaWiki Performance Optimisation
• VisualEditor Setup Guide

External Links

• MediaWiki Manual: Configuring File Uploads
• MediaWiki Manual: $wgFileExtensions
• MediaWiki Manual: $wgMaxUploadSize
• MediaWiki Manual: Security - Upload Security
• MediaWiki Help: Images