Your files stay yours

Guides › mPDF › Images in mPDF

Images in mPDF

Written for mPDF 8.2 on PHP 8.1+. Updated 2 November 2026.

mPDF embeds images from <img> tags and CSS backgrounds. Most image problems are about where mPDF looks for the file, or what size it decides to print it at.

Formats

JPEG, PNG (including transparency), GIF, BMP, WMF and SVG all work, and recent 8.x releases also read WebP. JPEGs are embedded without recompression. PNGs with an alpha channel make larger files, so use JPEG for photos.

Where images come from

<img src="images/logo.png">                         <!-- relative to the running script -->
<img src="/var/www/app/public/logo.png">            <!-- absolute file path -->
<img src="https://example.com/logo.png">            <!-- fetched over HTTP -->
<img src="data:image/png;base64,iVBORw0KGgo…">      <!-- inline data URI -->
  • Local paths are fastest and the most reliable. A relative path is resolved from the working directory of the script, not from where your HTML template lives, which catches people out. Set $mpdf->setBasePath() to the folder your relative URLs should resolve against.
  • Remote URLs cost a network request per image, and they fail silently if the server can’t reach the URL. Download images first when you can.
  • Images you already have in memory can be passed without writing a file:
$mpdf->imageVars['chart'] = $pngBytes;
$mpdf->WriteHTML('<img src="var:chart" width="160mm">');

Size: set it explicitly

Without a width or height, mPDF sizes an image from its pixel dimensions and the img_dpi setting (96 by default). A 1200-pixel-wide photo then prints at about 317 mm, wider than A4. Always give images a size in print units:

<img src="photo.jpg" style="width: 80mm;">

For sharp printing, supply roughly 150–300 pixels per inch of printed size, and no more. Oversized images make the PDF heavy without looking any better.

SVG

SVG is drawn as vector graphics, so logos and charts stay crisp at any zoom. mPDF supports a solid subset of SVG: paths, shapes, gradients and text. Very complex charts with filters, masks or embedded CSS may not render fully. Export those to PNG instead.

Debugging missing images

Turn on errors while developing:

$mpdf->showImageErrors = true;

mPDF will then stop with the exact reason (file not found, unsupported format, SSL failure) instead of leaving a blank space.