From MediaWiki.org
Jump to navigation Jump to search
This extension comes with MediaWiki 1.21 and above. Thus you do not have to download it again. However, you still need to follow the other instructions provided.
MediaWiki extensions manual
Crystal Clear action run.svg
Release status: stable
Implementation Media
Description Allows to handle PDF files like multipage DJVU
Author(s) Martin Seidel (xarax)
MediaWiki 1.25+
PHP 5.4+
Database changes No
License GNU General Public License 2.0 or later
Example commons.wikimedia.org
  • $wgPdfProcessor
  • $wgPdfPostProcessor
  • $wgPdfInfo
  • $wgPdftoText
  • $wgPdfOutputExtension
  • $wgPdfHandlerDpi
  • $wgPdfCreateThumbnailsInJobQueue
  • $wgPdfHandlerJpegQuality
Hooks used
Translate the PdfHandler extension if it is available at translatewiki.net
Check usage and version matrix.
Vagrant role pdfhandler
Issues Open tasks · Report a bug

The PdfHandler extension shows uploaded pdf files in a multipage preview layout.

With the Proofread Page extension, pdfs can be displayed side-by-side with text. This allows users to transcribe books and other documents.[1]


This extension requires the following packages to be installed first:

Package Description Link
ghostscript for gs Renders the page images http://www.ghostscript.com
imagemagick dynamic resizing and thumbnailing of images http://www.imagemagick.org/script/install-source.php for instructions on how to install
xpdf-utils for pdfinfo Extract metadata from pdf. If you see "0 × 0 pixel" on the file description of a PDF, you lack this package. http://www.foolabs.com/xpdf/download.html

On Ubuntu and Debian, the "poppler-utils" package can be used instead of xpdf-utils.

Type into a shell which gs convert pdfinfo pdftotext to see if you have the above installed first.


Note Note: The required software above must be installed first.

  • Download and place the file(s) in a directory called PdfHandler in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    wfLoadExtension( 'PdfHandler' );
  • Configure as required (see also the examples provided)
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

To users running MediaWiki 1.24 or earlier:

The instructions above describe the new way of installing this extension using wfLoadExtension() If you need to install this extension on these earlier versions (MediaWiki 1.24 and earlier), instead of wfLoadExtension( 'PdfHandler' );, you need to use:

require_once "$IP/extensions/PdfHandler/PdfHandler.php";


  • A user can display PDF files as an image, showing a single page at a time, like so: [[File:myPdfFile.pdf|page=1|600px]]. The page and size parameters are optional; the default page is page #1. Instead of a size-parameter, you can also use the thumb-parameter, with or without captions: [[File:myPdfFile.pdf|page=1|thumb|My PDF]].[2]
  • Because PdfHandler extends ImageHandler, you can use all the arguments that you would for an Image -- for example: thumb, right/left, caption, border, link, etc.
If you would like to present a 2-page pdf, for example, do the following: [[File:myPdfFile.pdf|page=1]] [[File:myPdfFile.pdf|page=2]]
  • The main usage of the PdfHandler extension is without user interaction. If you upload a new pdf file, the metadata will be stored in the database, and then this file can be shown in a multipage preview layout like the djvu handler does. Without this extension, pdfs will not display properly when uploaded.
  • Additionally, this extension allows Extension:ProofreadPage to handle pdfs in side-by-side view for transcribing/proofreading, as is done on Wikisource


You can (or, depending on the operating system of the server, will have to) set some variables in the "LocalSettings.php" file:

$wgPdfProcessor (default = "gs")
path to your ghostscript implementation
$wgPdfPostProcessor (default = "convert")
path to your imagemagick convert
$wgPdfInfo (default = "pdfinfo")
path to your pdfinfo
$wgPdftoText (default = "pdftotext")
path to your pdftotext
$wgPdfOutputExtension (default = "jpg")
extension of the files to be rendered
$wgPdfHandlerDpi (default = "150" )
resolution in dpi
The extension extracts a bitmap image for each page of the PDF, using this resolution (dpi = dots per inch). For example, a PDF page with the European size A4 is 210 mm wide, corresponding to 595 points (at 72 dpi). This yields an image 1240 pixels wide (at 150 dpi). If instead this parameter is set to 300 dpi, the width will be 2480 pixels.
$wgPdfHandlerJpegQuality (default = "95" / since MW 1.24+ )
Quality level, which the post processor should use.
$wgPdfCreateThumbnailsInJobQueue (default = "false")
Puts creating pages' thumbnails into a job queue, so they do not have to be created while browsing a file page, but during normal wikibrowsing. Be advised that setting this to "true" may significantly increase CPU load of your webserver on a high-traffic website. Job queue was designed to perform quick tasks on page views, and creating thumbnails can be included into that queue, according to this definition. Nevertheless, as quick as it is, it also requires certain CPU load to convert PDF pages to another format. The solution to that would be either setting $wgJobRunRate to rather small value (ie. 0.05) or disabling job queue on the high-traffic wiki and setting up another server to do just job queue (like Wikimedia did).
Variables below are not specific to this extension


Note Note: This is identical to the default settings for this extension.

$wgPdfProcessor = 'gs';
$wgPdfPostProcessor = $wgImageMagickConvertCommand; // if defined via ImageMagick
// $wgPdfPostProcessor = 'convert'; // if not defined via ImageMagick
$wgPdfInfo = 'pdfinfo';
$wgPdftoText = 'pdftotext';


$wgPdfProcessor = '/usr/bin/gs'; 
$wgPdfPostProcessor = $wgImageMagickConvertCommand; // if defined via ImageMagick
// $wgPdfPostProcessor = '/usr/bin/convert';  // if not defined via ImageMagick
$wgPdfInfo = '/usr/bin/pdfinfo'; 
$wgPdftoText = '/usr/bin/pdftotext';


$wgPdfProcessor = 'C:\Programme\gs\gs8.60\bin\gswin32.exe';
$wgPdfPostProcessor = $wgImageMagickConvertCommand; // if defined via ImageMagick
// $wgPdfPostProcessor = 'C:\Programme\ImageMagick-6.6.2-Q16\convert.exe'; // if not defined via ImageMagick
$wgPdfInfo = 'C:\Programme\xpdf-3.02pl1-win32\pdfinfo.exe';
$wgPdftoText = 'C:\Programme\xpdf-3.02pl1-win32\pdftotext.exe';


To install dependencies via Homebrew:

brew install ghostscript xpdf imagemagick
$wgPdfProcessor = '/usr/local/bin/gs';
$wgPdfPostProcessor = $wgImageMagickConvertCommand; // if defined via ImageMagick
// $wgPdfPostProcessor = '/usr/local/bin/convert'; // if not defined via ImageMagick
$wgPdfInfo = '/usr/local/bin/pdfinfo';
$wgPdftoText = '/usr/local/bin/pdftotext';


  • If PDFs don't display after upload, make sure that MediaWiki can execute the pdfinfo command and that $wgPdfInfo is set properly. Also check your error log, and make sure that your host hasn't disabled running external commands.
  • If PDFs don't show properly after installation you may need to use the maintenance scripts refreshImageMetadata.php -f and rebuildImages.php -f
  • If PDFs are rendered randomly check if the "C.UTF-8" locale is available on your server by running locale -a and make sure that $wgShellLocale is set to this locale.

Special solutions[edit]

If you are running this extension on a windows machine with PHP7 you may need to enclose the commands in the PdfHandler.image.php file.

If you get error messages like <yourpath> is not recognized as an internal or external command, operable command or batch file.

or The filename, directory name, or volume label syntax is incorrect. and if your thumbnails neither are creating nor displaying meta data such as height, width etc. this may fix your problem!

This message appears, when PDFHandler retrieve metadata from pdf file via running pdfinfo.exe and pdftotext.exe.

$cmd = '"' . wfEscapeShellArg( $wgPdfInfo ) . 
 " -enc UTF-8 " . # Report metadata as UTF-8 text...
 " -l 9999999 " . # Report page sizes for all pages
 " -meta " .      # Report XMP metadata
 wfEscapeShellArg( $this->mFilename ) . '"';


$cmd = '"' . wfEscapeShellArg( $wgPdftoText ) . ' '. wfEscapeShellArg( $this->mFilename ) . ' - "';

The function is called retrieveMetaData. This happens due a bug in PHP.

Tested with MW 1.27 PHP 7.0.9 x64 on an Windows Server 2012 R2 and an Windows Server 2008 R2.

Thanks to the user Urmatskih


  1. This allows users to transcribe books and other documents as is commonly done with DjVu files (particularly in Wikisource).
  2. This single page option was introduced quite long ago (r25575)

See also[edit]