Open main menu

Meta β

Help:Images and other uploaded files

MediaWiki Handbook: Contents, Readers, Editors, Moderators, System admins, Researchers +/-
Languages: English · dansk · Deutsch · français · italiano · 日本語 · polski · português do Brasil · русский · shqip · Tiếng Việt · 中文(台灣)‎

You can upload files through MediaWiki and embed them in textual pages. In other words, to embed an image, the image file has to be uploaded. Also other files can be uploaded, see below. In earlier versions of MediaWiki, the term "image" was used for any uploaded file; the current version uses the term (and namespace) "file:" or "media:" instead.

When a file is uploaded, a file page (also called "image description page") will be created, with a page name consisting of the file name (including extension), prefixed with "File:" (or in general the value of variable {{ns:File}} (MediaWiki 1.14 or following) or {{ns:Image}} (MediaWiki 1.13 or earlier).

Media files like images can be embedded into text using the regular internal link syntax. Images can also be resized to fit better within the page, see below.

A group of wikis may have designated one "preferred wiki" to upload files to, with sharing of those files enabled. Among Wikimedia wikis, Wikimedia Comm[1]ons works for this. If images are uploaded to Wikimedia Commons, they can be used in all Wikimedia wikis. Images uploaded on another wiki (e.g. Wikipedia) can only be used in pages of that wiki. Thus this should be done only if there is a special reason for it, such as locally replacing an image from Commons with a local version without changing the links.

Images can also be produced by the system from specifications in wikitext:

Supported file typesEdit

By default, MediaWiki only allows you to upload certain types of files (extensions gif, jpg, jpeg, ogg and png). This is managed by the orders in includes/DefaultSettings.php [1]:

 * This is the list of preferred extensions for uploading files. Uploading files
 * with extensions not in this list will trigger a warning.
$wgFileExtensions = array( 'png', 'gif', 'jpg', 'jpeg', 'doc', 'docx', 'xls', 'xlsx', 'pdf' );

/** Files with these extensions will never be allowed as uploads. */
$wgFileBlacklist = array(
    # HTML may contain cookie-stealing JavaScript and web bugs
    'html', 'htm', 'js', 'jsb', 'mhtml', 'mht',
    # PHP scripts may execute arbitrary code on the server
    'php', 'phtml', 'php3', 'php4', 'php5', 'phps',
    # Other types that may be interpreted by some servers
    'shtml', 'jhtml', 'pl', 'py', 'cgi',
    # May contain harmful executables for Windows victims
    'exe', 'scr', 'dll', 'msi', 'vbs', 'bat', 'com', 'pif', 'cmd', 'vxd', 'cpl' );

/** Files with these mime types will never be allowed as uploads
 * if $wgVerifyMimeType is enabled.
$wgMimeTypeBlacklist= array(
    # HTML may contain cookie-stealing JavaScript and web bugs
    'text/html', 'text/javascript', 'text/x-javascript',  'application/x-shellscript',
    # PHP scripts may execute arbitrary code on the server
    'application/x-php', 'text/x-php',
    # Other types that may be interpreted by some servers
    'text/x-python', 'text/x-perl', 'text/x-bash', 'text/x-sh', 'text/x-csh',
    # Windows metafile, client-side vulnerability on some systems

/** This is a flag to determine whether or not to check file extensions on upload. */
$wgCheckFileExtensions = false;

 * If this is turned off, users may override the warning for files not covered
 * by $wgFileExtensions.
$wgStrictFileExtensions = true;

/** Warn if uploaded files are larger than this (in bytes), or false to disable*/
$wgUploadSizeWarning = false;

Take in to account that there is a blacklist of file extensions and mime types. For reasons of security, executable programs are not allowed by default. Also some file types that could be uploaded in the past can no longer be uploaded, but the files already uploaded can still be used.

SVG images uploaded earlier can be linked to, but not be directly embedded, e.g. Media:Wikipedia3fnlc1.svg (image description page) - see also m:SVG image support.

For videos see m:Video policy.


To upload a file, in general, go to Commons, log in there, and upload the file using the upload link commons:Special:Upload[2]. In the menu on the left under "toolbox" you will have a link named "Upload file". If you want to upload the file to one of the other wikis, you can follow the same steps as at Commons, but be sure to refer to the local guidelines.

Before uploading please ensure that you have rights to upload and redistribute the file(s) in question, and that they comply with any further licensing requirements of the Wikimedia Commons project and other criteria for inclusion. Please note that as with wiki pages, others may edit or delete your uploads if they think it serves the project, and you may be blocked from uploading if you abuse the system.

The preferred formats are JPEG for photographic images with millions of colors and shades; PNG for fixed-color pixelated images such as icons; SVG for structured drawings, logos; and OGG for audio.

Once you get to the upload page, on most browsers, you will see a "Browse..." button, which will bring up your operating system's standard file open dialog. Choosing a file will fill the name of that file into the text field next to the button. Upload the file under a suitable name, because renaming the file after uploading is not possible. The file name doesn't need to be the same as the file name stored on your computer. Please name your files descriptively to avoid confusion and make sure that the file name has the proper extension. Consider using the first 20 characters of the image name for as much compact information as possible, since only these are usually shown on category pages. The file names are case-sensitive (this applies even for the file name extension), except, in most wikis, for the first character.

When choosing a name for a file on Commons, do not use a name that is already in use on any project on which the file may be used. This is because a file on Commons with the same name as the one on the local is not accessible for embedding in the local project. However, if the new file on Commons should replace the local ones, and the local ones will therefore be deleted, you may use the same name.

You must also check the box affirming that you are not violating any copyrights by uploading the file. Press the "Upload file" button to finish the upload. This may take some time if you have a slow internet connection.

When a file is uploaded with the same name as an existing one, the old one is replaced, and the system will warn against overwriting. When a media file is replaced by uploading a new one with the same name (e.g. an image in an article is replaced), this does not show up in the page history of the article, nor in the Related changes of the article, nor in the revision history of the image description page (unless the description section is also changed). However, it is recorded in the Image History section of the image description page, and it changes m:Upload log. Therefore, to watch changes in images in an article, it is not sufficient to watch the article itself. Watching the image description pages will help you find the change in the file (from MediaWiki 1.13).

Protection of an image page is automatically also protection of the image itself: i.e. a new image under the name of the existing image can only be uploaded by a sysop.

When replacing or deleting a file on Commons, all projects that use the file are affected. Therefore it is important that the image page on Commons is linked to the local image pages of that file on all projects that use it. On these, even if they have never been created explicitly and therefore have an empty editable part, the "file links" section shows the local pages that use the file.

See commons:Commons:First steps for more detail.

Special:Imagelist provides the same information as the Upload log, but it uses the user's local time instead of the default time (set to Coordinated Universal Time for Wikimedia projects). In addition it gives the file sizes. Further it allows loading of portions and sorting by size in addition to sorting by date, and it has not only links to the image description pages, but also directly to the images.

Embedding internal filesEdit

To embed an internal file in a text, you just have to specify its file name with the internal link syntax ([[ ]]). Thus, [[image:tst.png]] gives  .

Here, "internal" refers to both the same project and Commons. An image name is assumed to refer to the one in the same project if it exists there, otherwise to one on Commons. If neither exists a link to the upload page appears, with class="new" ("red link"). The link is rendered the same as one to the edit page of the non-existing image page, except that the former shows the canonical form of the pagename.

Only images proper can be automatically presented, sound is not automatically played.

An embedded internal image automatically links to the image page, which shows the full image, or, depending on preferences, a reduced version with a link to the full version. The page also provides info about the image.

Images on MediaWiki:Bad image list cannot be embedded; they appear as a regular link to the image page. Exceptions to allow a listed image on particular relevant articles can be added. See, for example, w:en:MediaWiki:Bad image list.


The internal-link style markup for embedding a file can take various options separated with a pipe character ("|"). In brief, they are [[Image:{name}|{type}|{location}|{size}|{upright}|{border}|{caption}]].

'thumb' or 'frame'. Causes image to be displayed with specific formatting (see below).
'left', 'right', 'center' or 'none'. Determines placement of the image on the page.[3] Defaults to 'right' if the type is 'thumb' or 'frame'. The combination thumb and none can be useful in a table, to allow a caption but reduce the space around the image. Text that follows the image with location left or right floats, in the case of center or none it does not (if necessary, reduce the browser window width to see this in the examples). An image without the specification thumb or frame, and without location specified (not even none) is displayed inline.
{width}px or {width}x{height}px, reduces or enlarges an image without specified type, reduces an image if thumb is specified. Even if width and height are specified the image will keep its original aspect ratio: either the width or the height will be equal to the specified maximum, whichever allows the other to be no larger than the maximum.
for use only on images that are taller than they are wide. Adjusts a thumbnail's size to factor times the default thumbnail size, rounding the result to the nearest multiple of 10 pixels. For instance, "upright=1.5" makes the image larger, which is useful for maps or schematics that need to be larger to be readable. As a guide "upright=1" is the same width as a standard thumbnail, and "upright=0.75" is the same as using "upright" alone.
adds a border around the image.
To allow an image to link to an arbitrary title, URL or just nowhere.
See w:wp:Alternative text for images.
Any element which cannot be identified as one of the above is assumed to be caption text. If there is more than one the last one is effective, even if it's an empty string. Specifying a caption parameter is strongly recommended for the sake of accessibility. Images without type do not have a caption, the caption parameter becomes a "title"-attribute, which is shown in the hoverbox. A real caption can contain links.

In the case of a non-existing image, a link to the upload page is provided. If type has been specified this is still applied, with the caption. Location is also applied. Remaining elements, even image size, are treated like caption: the last one of any of these is effective as label of the upload link.

Single pipes inside a pair of double rectangular brackets, such as in link and image syntax, are shielded by these brackets from being interpreted as table syntax. However, this does not apply to consecutive pipes, which might occur in the expanded wikitext for image syntax if an optional parameter is not applicable. Thus in the case of an optional parameter, make the pipe optional as well. A pipe in e.g. the then- or else part of a conditional parser function can be coded as {{!}}, due to Template:!. Alternatively, add an unconditional space in the image syntax: a pipe-space-pipe combination is not a double pipe, so not taken as table syntax, while a parameter position containing just a space is ignored in the interpretation of the image syntax.

In cases where text floats around the image, use <br clear="all" />, or on projects that have Template:Clr or Template:- {{clr}} or {{-}} to continue below the image(s).

An image can be in-line, a floating block, or like a paragraph (i.e., without text on the sides).


a[[Image:Tst.png|x]]b → a b [2]

a[[Image:Tst.png|5px|x]]b → a b [3]

a[[Image:Tst.png|20px|x]]b → a b [4]

The default thumbnail width (also applicable to frameless) can be set in the preferences, so typically it is better not to specify "px". Either way, showing an enlargement of the stored image is not possible.

a[[Image:Tst.png|frameless|x]]b → a b [5]

a[[Image:Tst.png|frameless|5px|x]]b → a b [6]

a[[Image:Tst.png|frameless|20px|x]]b → a b [7]

Floating, neither thumb nor frameEdit

With the differences mentioned above, this applies to frameless too.

a[[Image:Tst.png|left|x]]b → a

b [8]

a[[Image:Tst.png|left|5px|x]]b → a

b [9]

a[[Image:Tst.png|left|20px|x]]b → a

b [10]

a[[Image:Tst.png|right|x]]b → a

b [11]

a[[Image:Tst.png|right|5px|x]]b → a

b [12]

a[[Image:Tst.png|right|20px|x]]b → a

b [13]

Blank on the side(s), neither thumb nor frameEdit

With the differences mentioned above, this applies to frameless too.

a[[Image:Tst.png|center|x]]b → a

b [14]

a[[Image:Tst.png|center|5px|x]]b → a

b [15]

a[[Image:Tst.png|center|20px|x]]b → a

b [16]

a[[Image:Tst.png|none|x]]b → a

b [17]

a[[Image:Tst.png|none|5px|x]]b → a

b [18]

a[[Image:Tst.png|none|20px|x]]b → a

b [19]

Floating, thumb with captionEdit

Both the image itself and an "enlarge" icon in the frame links to the image page.

a[[Image:Tst.png|thumb|x]]b → a


b [20]

a[[Image:Tst.png|thumb|5px|x]]b → a


b [21]

a[[Image:Tst.png|thumb|left|x]]b → a


b [22]

a[[Image:Tst.png|thumb|left|5px|x]]b → a


b [23]

a[[Image:Tst.png|thumb|right|x]]b → a


b [24]

a[[Image:Tst.png|thumb|right|5px|x]]b → a


b [25]

Blank on the side(s), thumb with captionEdit

a[[Image:Tst.png|thumb|center|x]]b → a


b [26]

a[[Image:Tst.png|thumb|center|5px|x]]b → a


b [27]

a[[Image:Tst.png|thumb|none|x]]b → a


b [28]

a[[Image:Tst.png|thumb|none|5px|x]]b → a


b [29]

Limitation of thumbEdit

Like with frameless, showing an enlargement of the stored image is not possible, for example:

a[[Image:Tst.png|thumb|20px|x]]b → a


b [30]

Floating, frame with captionEdit

a[[Image:Tst.png|frame|x]]b → a


b [31]

a[[Image:Tst.png|frame|left|x]]b → a


b [32]

a[[Image:Tst.png|frame|right|x]]b → a


b [33]

Blank on the side(s), frame with captionEdit

a[[Image:Tst.png|frame|center|x]]b → a


b [34]

a[[Image:Tst.png|frame|none|x]]b → a


b [35]

Limitation of frameEdit

Display in other than the stored size is not possible, for example:

a[[Image:Tst.png|frame|5px|x]]b → a


b [36]

a[[Image:Tst.png|frame|20px|x]]b → a


b [37]

Multiple images with floating textEdit

a[[image:tst.png|left|x]]b[[image:tst.png|left|x]]c → a


c [38]

a[[image:tst.png|thumb|left|x]]b[[image:tst.png|frame|left|x]]c → a




c [39]

a[[image:tst.png|thumb|left|x]]b[[image:tst.png|frame|right|x]]c → a




c [40]


By default an image is linked to its image page: [[Image:Tst.png|x]]  [41]

The link parameter can modify this.

Important note: This should only be used with images that don't require attribution (mostly public domain images). Other images must link to the image description page, otherwise they violate copyrights.
Note: This (appears to) work only with non-thumbnailed images.
  • Without link: [[Image:Tst.png|link=]]  [42]
  • With internal link: [[Image:Tst.png|link=Main Page|x]]  [43]
  • With interwiki link: [[Image:Tst.png|link=en:Clock|x]]  [44]
  • With external link: [[Image:Tst.png|link=|x]]  [45]

The methods above do not work with some versions with thumb and caption. Instead try brackets;

  • [[Image:Pic.jpg|thumb|caption [link=] ]]
  • Without link the caption parameter does not work: [[Image:Tst.png|link=|x]]  [46]


The gallery-tag is a quick way to show thumbnails in a number of columns. The images will have a single fixed width. The gallery-tag also allows text to take the position of an image. The resulting HTML is that of a table with class="gallery", with cells with class="gallerybox".

Each entry is of the form File:image name or File:image name|caption, possibly with links.

A title to the gallery can be given with the caption= attribute, which may contain wikilinks but not external links. The number of images per row can be set by the perrow= attribute; the default is 4. The width and height per image (the widths= and heights= attributes) can be set as well. If both are unset, they default to 120px. If you only set the width, the height never exceeds 120px, and vice versa. The height of the caption depends on the image width and varies per image with the length of the caption. The height of each table row is the maximum height needed in that row for an image with a caption.

Example (note that "File:" is optional, and that |link= can be used to make the image a link to a specified location, instead of to the image):

<gallery caption="Sample gallery" widths="100px" heights="100px" perrow="6">
File:Drenthe-Position.png|[[w:Drenthe|Drenthe]], the least crowded province
File:Friesland-Position.png|[[w:Friesland|Friesland]] has many lakes
Zuid_Holland-Position.png|[[w:South Holland|South Holland]], the most crowded province
Zeeland-Position.png|link=nl:Zeeland (provincie)


Note that for SVG images that use <switch>, the language can be specified:

Gerrit patchset 25838 test.svg|English<br/>(default for this image)
Gerrit patchset 25838 test.svg|lang=de|Deutsch (German)
Gerrit patchset 25838 test.svg|lang=es|español (Spanish)
Gerrit patchset 25838 test.svg|lang=fr|français (French)
Gerrit patchset 25838 test.svg|lang=it|italiano (Italian)


Galleries in categoriesEdit

A gallery of images on a category page is automatically shown as the fourth section of this category page. The first 20 characters of the image name are shown, with dots if that is not the full name. Both the image and the name link to the image page, instead of just the image. No alternative text or other links are possible. The file size is also shown.

For a comparison, see commons:Category:William-Adolphe Bouguereau and commons:William-Adolphe Bouguereau.

Images in a tableEdit

Using table syntax, with images in separate cells, and the image syntax explained elsewhere on this page, gives more control over size, layout, captions, etc. than each of the two methods above. However, only a category page automatically gives file sizes.

Example of an image table:

{| border="1"
|+'''Provinces of the Netherlands'''
| valign="top"|
[[File:Drenthe-Position.png|thumb|left|150px|[[w:Drenthe|Drenthe]], the least crowded province]]
| valign="bottom"|
| valign="top"|
| valign="top"|
| valign="top"|
[[File:Zuid_Holland-Position.png|thumb|left|100px|[[w:South Holland|South Holland]], the most crowded province]]
| valign="top"|


Provinces of the Netherlands
Drenthe, the least crowded province
South Holland, the most crowded province

Note that, with this method, each image has a width specified by the size option, if any, and a height depending on whether there is caption or not, and how long the caption is. The width of a column is determined by the widest image in it, and the height of the row is determined by the tallest image in it.

Template:Gallery supports making a gallery using table syntax.

The parameters |left and |right may give complications inside a table (and may not be needed anyway), depending on the browser. In IE the first table sometimes (!) displays text through the image:

{| border="1"
| [[File:Crystal_Clear_app_clock.png|left]]
|abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz
{| border="1"
| [[File:Crystal_Clear_app_clock.png]]
|abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz
  abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz abcdefghijklmnopqrstuvwxyz


To link to an uploaded file, e.g. Flag of Somalia.svg, use [[Media:Flag of Somalia.svg]] instead of [[Image:Flag of Somalia.svg]], giving Media:Flag of Somalia.svg; to link to the image description page, use [[:Image:Flag of Somalia.svg]], giving Image:Flag of Somalia.svg (the first colon is not displayed). In the case of non-image uploads, e.g. office files (if allowed by the system), the keyword 'media' is used even though office documents are not typically classed as media, in the context of audio/video etc.

Piped links work as usual. Existence detection, with a link to the edit page if the page does not exist, works as usual, but is applicable for the image page, not the file.

Interwiki linking style gives a link to the image page. If interlanguage links would be applicable, use a colon in front of the language code, e,g. [[:de:Bild:Europa-Pos.png]], to avoid the link being put in the margin. For embedding (if possible, see below) and linking to the file itself, use external link style.

External link syntax is as usual. However, if you want a link to an image proper on a page of a project that allows embedded external images, use a bracketed link syntax and not just the URL, to prevent embedding.

Below one can see the result of the three types of internal link style and external link style on this project. To test this in another project, copy the wikitext there. If applicable, check also the interlanguage links at the margin of the page. Note that some links go to the image description page, others just to the image itself.

Navigational mapsEdit

Navigational maps like [48] have map areas linked to pages. The html with <area> tags can not be put in the wikitext. However, there are the following possibilities:

  • With ImageMap (MW 1.9+) you can define areas in an image and link to wiki pages when clicking on that area.
  • EasyTimeline allows the creation of an image and a page embedding that image, with rectangular map areas defined by <area> tags in the html. The title of a link to a non-internal page is only the domain name, e.g. "". The length and width of the rectangle can not be controlled, except that it depends on the length of the link label and its font size. In case of overlap of rectangles one has to look at the hoverbox or statusbar to avoid following the wrong link. In case of much overlap it may not be possible to use all links.
  • One can divide an image in rectangles, like in these chess and go positions, or superimpose an area with images (see above) and link each rectangle/image to the desired target by means of a redirect on the image page (provided that the target is internal).

See also:

Example using ImageMapEdit


Image:Sudoku dot notation.png|300px
circle  320  315 165 [[w:1|1]]
circle  750  315 160 [[w:2|2]]
circle 1175  315 160 [[w:3|3]]
circle  320  750 160 [[w:4|4]]
circle  750  750 160 [[w:5|5]]
circle 1175  750 160 [[w:6|6]]
circle  320 1175 160 [[w:7|7]]
circle  750 1175 160 [[w:8|8]]
circle 1175 1175 160 [[w:9|9]]
default [[w:Number|Number]]

Output of this example:

See also:

Examples using EasyTimelineEdit

Example 1

ImageSize  = width:400 height:150
PlotArea   = width:400 height:150 left:0 bottom:0
TimeAxis  = orientation:vertical # dummy, required
Period    = from:0 till:1 # dummy, required
Define $s = fontsize:XL
TextData  =
  pos:(50,120) $s text:[|o Leiden]
  pos:(150,110) $s text:[|o Alphen aan den Rijn]
  pos:(10,80) $s text:[|o The Hague]
  pos:(50,40) $s text:[|o Rotterdam]



Example 2

Preset     = TimeHorizontal_AutoPlaceBars_UnitYear
ImageSize = width:500 barincrement:50
Period     = from:0 till:12
Define $s = fontsize:XL
BackgroundColors = canvas:white
  bar:a from:3 till:4 $s text:[|Leiden]
  bar:a  from:6 till:7 $s text:[|Alphen aan den Rijn]
  bar:b  from:1 till:2 $s text:[|The Hague]
  bar:c  from:3 till:4 $s text:[|Rotterdam]




Some attempts for other alternatives (note the hover boxes):


Ascii art map, with both the city outline and the label clickable:

   xxx Leiden

xxxx The Hague

       xxxxx Rotterdam

When external images can be embedded:

The HTML titles are "w: Leiden", etc., the alt attribute is "Tst.png". Opera shows the title in the hoverbox, and also the url, IE only shows the titles.

With labels: Leiden The Hague Rotterdam

See also m:Maps, m:Maps' clickability.

For using an image as a link to another document, see Help:Navigational image. For more possibilities, see en:Wikipedia:Extended image syntax. Also, the source of existing pages with images are useful as examples.

Template for showing links to files with appropriate iconsEdit

For a template to enable files to be shown as links with relevant icons, as well as a link to the file's wiki page, see here.

This is for wikis that support embedding external images - which is most personal, corporate and organizational wikis based on MediaWiki. Notable exceptions are Wikipedia and Meta. Because Meta can't render this template, here is an image of how the template appears: MetaWikiPedia:Image:PDF file example.png

See alsoEdit

External linksEdit

  1. "Example Domain". Retrieved 2017-09-07. 
  2. "Example Domain". Retrieved 2017-09-07. 
  3. class="floatleft", class="floatright", class="center" with class="floatnone", and just class="floatnone". The actual position depends on css.