InstantCommons - MediaWiki
Jump to content
From mediawiki.org
Translate this page
Languages:
Kadazandusun
Nederlands
Türkçe
dansk
italiano
polski
português do Brasil
slovenčina
svenska
čeština
русский
ပအိုဝ်ႏဘာႏသာႏ
中文
Enter the name of an image from Commons on any MediaWiki installation ...
... and the image is fetched from Commons and embedded into the page
InstantCommons
is a feature of MediaWiki to allow the usage of any uploaded media file from the
Wikimedia Commons
in any MediaWiki installation world-wide.
Rationale
As of November 2023,
Wikimedia Commons
, the central media repository hosted by the
Wikimedia Foundation
, contains over 100 million files.
Each of these files is available under a free content license or in the public domain; there are no other restrictions of use beyond those relating to use of official insignia or trademarks.
Licenses which limit commercial use are considered non-free.
As awareness of the Commons grows, so does the desire of external parties to use content included therein, and to contribute new material.
It is currently technically possible to load images directly from Wikimedia's servers in the context of any webpage. Such hotlinking is allowed, but it is problematic for multiple reasons:
It does not respect the license terms of the image, and does not allow for other metadata to be reliably transported
Besides failing to properly credit the author of the media file, it also does not give credit to Wikimedia
It consumes Wikimedia bandwidth on every pageview (unless the image has been cached on the client side or through a proxy; this functionality is currently disabled by default)
It does not facilitate useful image operations such as thumbnail generation and captioning and is difficult to use in the context of a wiki, particularly for standard layout operations
It is tied to URLs as resource identifiers, which complicates mirroring
It creates an untrackable external usage web, where any change on Wikimedia's side necessarily affects these external users
It does not permit offline viewing, which is crucial in countries which have only intermittent network access.
InstantCommons seeks to address all this by providing an easy method for (cached) loading of images and metadata from Wikimedia's servers.
Although caching functionality is part of the objective, it has been disabled since MediaWiki 1.27.2/1.28.1.
InstantCommons was first implemented within MediaWiki, allowing for all MediaWiki image operations (thumbnailing, captioning, galleries, etc.) to be performed transparently.
Other wiki engines can implement InstantCommons-like functionality using the API operations described below.
Basic feature set
During the installation, the site administrator can choose whether to enable InstantCommons. Ideally, however, the feature should be enabled by default (provided a writable upload directory is specified) to allow the largest possible number of users to use Wikimedia Commons content.
If the feature is enabled, the wiki behaves like a Wikimedia project, that is, if an image or other media file is referred to which exists on Commons, it can be included in a wiki page like a locally uploaded file by specifying its name. Local filenames take precedence over Commons filenames.
Configuration
Default method: $wgUseInstantCommons
For enabling InstantCommons in MediaWiki version 1.16 or later, it is sufficient to add this line to your
LocalSettings.php
(see
$wgUseInstantCommons
for details):
$wgUseInstantCommons
true
Classic InstantCommons with local thumb caching
Default InstantCommons as enabled through $wgUseInstantCommons uses thumb images hotlinked from Wikimedia.
This may be slow and may also interfere with file caching (broken links).
If you would like to generate and use thumbs on your local server, do not use
$wgUseInstantCommons
Instead, insert this code into LocalSettings.php as described here:
Manual:$wgForeignFileRepos#Usage
$wgForeignFileRepos
[]
'class'
=>
ForeignAPIRepo
::
class
'name'
=>
'commonswiki'
// Must be a distinct name
'apibase'
=>
'https://commons.wikimedia.org/w/api.php'
'hashLevels'
=>
'fetchDescription'
=>
true
// Optional
'descriptionCacheExpiry'
=>
43200
// 12 hours, optional (values are seconds)
'apiThumbCacheExpiry'
=>
86400
// 24 hours, optional, but required for local thumb caching
];
Using files via InstantCommons
A picture from Wikimedia Commons embedded in this Wiki
With InstantCommons enabled, you can choose any image from Wikimedia Commons (e.g.
this one
), click the "Use this file" button (the button with the wiki icon
next to) and paste the markup in your wiki.
In our example, pasting
[[File:Wikipedia-Marker-commons.svg|thumb|A picture from Wikimedia Commons embedded in this Wiki]]
will render the thumbnail (as can be seen on the right side of this page).
Note that when using files in this way you will still need to respect any licensing and other file use legal requirements - see
Commons:Reusing content outside Wikimedia
Troubleshooting
Common thumbnail sizes
Since early 2026, Wikimedia image servers prefer to generate thumbnail images with predefined widths.
The rate limiting applied to sizes outside of the predefined widths is quite strict.
The
Common thumbnail sizes
can be used along with
$wgThumbnailSteps
to limit the image sizes used in the
‎<
img
HTML tags generated by MediaWiki.
When active these settings make your MediaWiki emit HTML that puts whatever
width
and
height
attribute is appropriate on generated
‎<
img
tags while also selecting the exact match or next largest width from the step sizes for the image requested from upload.wikimedia.org.
Adding
$wgThumbnailSteps
20
40
60
120
250
330
500
960
1280
1920
3840
];
and
$wgThumbnailStepsRatio
in your LocalSettings.php will make your MediaWiki match the expected sizes.
User-Agent Policy
If your wiki is throttled by Wikimedia Commons, please update to MediaWiki 1.45.0 (or MediaWiki 1.39.14+, 1.43.4+, or 1.44.1+) to comply with the
User-Agent Policy
Since late 2025, Wikimedia Commons may categorize API requests from your server as unidentified and throttle or block its requests.
This is due to enforcement of the
Wikimedia Foundation User-Agent Policy
and protects against increases in automated scraping.
Prior to MediaWiki 1.45, the User-Agent header in InstantCommons did not include a source URL, as required by the policy.
If you encounter a rate limit message when using InstantCommons, please upgrade to MediaWiki 1.45.0 (or MediaWiki 1.39.14+, 1.43.4+, or 1.44.1+) which sets a compliant header that includes the wiki's server URL.
High traffic wikis may additionally need to follow
Bot traffic requirements
by verifying the server's IP range.
HTTPS
Since June 2015, Wikimedia Commons can only be accessed using
HTTPS
. Some installs may be missing their root certificate store which prevents MediaWiki from contacting Commons over HTTPS. If InstantCommons stopped working, try:
Installing the
php curl
extension. (It is generally more reliable, and more likely to have proper certificates already installed.) On Debian/Ubuntu:
sudo apt-get install php-curl
Verifying you have an up-to-date certificate store. If you have the php curl extension installed, follow the instructions on
webaware
or
Talk:InstantCommons#Stop_working
Make sure the PHP function
curl_exec()
is not disabled in your web server.
SElinux
If your server OS implements SElinux, please take a look at the
dedicated section
on the
SELinux
settings page, and make sure HTTPD scripts and modules can access the network successfully.
If SElinux prevents HTTPD scripts and modules from connecting to Wikimedia Commons repository, the InstantCommons feature will simply not work.
Behind a firewall
If the server on which the wiki runs is behind a firewall, the wiki server must be granted outgoing http/https requests to commons.wikimedia.org and upload.wikimedia.org, for Instant Commons to work. The IP address ranges are found at
wikitech:IP addresses
If you need to use a proxy to access the internet from behind the firewall, see
$wgHTTPProxy
See also
Manual:$wgForeignFileRepos
– for the same functionality as InstantCommons but with other wikis
PhotoCommons
– WordPress plug-in to provide the same functionality
Examples of sites which are using InstantCommons
Extension:QuickInstantCommons
References
Retrieved from "
Category
MediaWiki development
InstantCommons
Add topic