Image formats & inclusion

When you write \includegraphics{plot} you are not handing LaTeX a filename. You are handing it a stem, and the graphicx package then appends extensions in a fixed order — .pdf, .png, .jpg and so on — taking the first file that exists. That one design decision is why a single source file compiles under pdfLaTeX, LuaLaTeX and dvipdfmx alike, and it is also why “I regenerated the PNG but the figure did not change” is such a common complaint. This page covers the options of \includegraphics, the search path set by \graphicspath, which image formats each engine actually reads, and how to read the errors when LaTeX says a file is not found.

graphicx and \includegraphics: why you leave the extension off

Image inclusion is the job of the standard graphicx package: declare \usepackage{graphicx} and then write \includegraphics[options]{name}. Leaving the extension off is the convention, and the reason is plain once you look inside. The pdfTeX driver file pdftex.def spells out the list of extensions to try, in this order: .pdf, .png, .jpg, .mps, .jpeg, .jbig2, .jb2. So if both plot.pdf and plot.png sit in the folder, the PDF always wins. When you re-export a chart as PNG and the figure refuses to change, an old plot.pdf is usually still lying next to it. Seen the other way round, it is precisely because you omit the extension that you can later swap a PNG for a PDF without touching a character of the manuscript. graphicx is an extended version of the older graphics package, the difference being that options arrive as key=value pairs; both ship in LaTeX's standard latex-graphics bundle, so there is nothing extra to install.

\documentclass{article}
\usepackage{graphicx}
\begin{document}
% no extension: graphicx tries .pdf, .png, .jpg ... in that order
\includegraphics[width=0.6\textwidth]{plot}
\end{document}

Writing the extension does more than switch off the automatic choice — it changes the wording of the error. When \includegraphics{plot} finds nothing, the search is being run by the LaTeX kernel, which says ! LaTeX Error: File 'plot' not found. When \includegraphics{plot.png} finds nothing, the driver answers instead: ! Package pdftex.def Error: File 'plot.png' not found: using draft setting. The first means “no extension matched”, the second means “that one file is missing”, and which of the two you get tells you where to look. Worth knowing: the mwe package in TeX Live installs example-image.pdf into the TeX tree itself, so \includegraphics{example-image} works from any directory on any machine. That is why the name turns up in every minimal example on the question sites.

Sizing an image: width, height, scale, keepaspectratio

In practice you almost always specify the size, and the convention is to give it relative to the page, as in width=0.8\textwidth. Absolute values like 8cm leave the figure behind the moment you switch to two columns or change paper size. \textwidth is the width of the text block; \linewidth is the width of the line currently being set, which shrinks to the box width inside a minipage or a subfigure. So writing width=\linewidth inside a box makes the image follow automatically when you later change that box. scale= multiplies the image's own natural dimensions, which suits the case where those dimensions are themselves meaningful, but it knows nothing about the text width and therefore overflows easily; width= is normally the safer choice.

Give both width= and height= and graphicx obediently honours both, so the aspect ratio breaks and the image is distorted. keepaspectratio prevents that: with it, the two values define a frame, and the image is scaled as large as it can be inside that frame while keeping its proportions. When pouring photographs into slots of a fixed size, you nearly always want it. One more option worth knowing for checking work is draft. It does not read the image at all; it sets an empty frame of the right dimensions with the filename printed inside, which makes trial compilations of a document with hundreds of figures dramatically faster. \usepackage[draft]{graphicx} applies it to the whole document.

Rotating and cropping: angle, trim, clip, viewport

angle= takes a rotation in degrees, measured counter-clockwise. angle=90 turns the image a quarter turn to the left, the standard move for putting a landscape chart on a portrait page. What deserves attention is the order in which you write angle= and width=, because graphicx applies keys in the order given. [angle=90,width=6cm] means “rotate, then fit the result to 6cm wide”; [width=6cm,angle=90] means “make it 6cm wide, then rotate” — and the final dimensions differ. Rotation happens about the bottom-left corner by default; origin=c moves the pivot to the centre and origin=tr to the top right.

To trim the edges of an image, pair trim= with clip. trim takes four values in the order left, bottom, right, top — an order inherited from the PostScript coordinate system, whose origin sits at the bottom left, which is why it does not match anyone's intuition. The default unit is bp (big point, one seventy-second of an inch). And always add clip: forget it and the part you meant to cut away is not discarded but spills out over the surrounding text. Negative values do the opposite and add margin, which is a neat way to open space around a figure. When you would rather name the crop as an absolute rectangle than as four amounts to shave off, use viewport=, again together with clip.

% half the text width
\includegraphics[width=0.5\textwidth]{photo}

% fit inside 8cm x 5cm without distortion
\includegraphics[width=8cm,height=5cm,keepaspectratio]{photo}

% rotate a quarter turn to the left, then scale the result
\includegraphics[angle=90,width=6cm]{diagram}

% shave 20bp left, 20bp bottom, 30bp right, 10bp top -- clip is mandatory
\includegraphics[trim=20 20 30 10,clip,width=6cm]{scan}

% page 3 of a multi-page PDF
\includegraphics[page=3,width=\linewidth]{report}

Pointing at a figures folder with \graphicspath

If your images live in a separate folder, add to the search path with \graphicspath. Wrap each directory in its own pair of braces — even when there is only one — and end each with a forward slash /, a forward slash on Windows too. The search order is easy to confirm by experiment: an image of the same name in the current directory wins outright, and failing that the directories are tried in the order written, first hit taken. So listing \graphicspath{{figures/}{old-figures/}} gives you a useful arrangement in which a new version in figures/ automatically shadows the old one, and only the figures you have not redrawn yet are picked up from old-figures/. A path containing spaces goes in quotes, as in {"my figures/"}. To change the list of extensions itself, use \DeclareGraphicsExtensions.

\usepackage{graphicx}
% braces around each directory, trailing slash on each, searched in this order
\graphicspath{ {figures/} {../shared-figures/} }

% narrow or reorder the list of extensions graphicx will try
\DeclareGraphicsExtensions{.pdf,.png,.jpg}

PDF or PNG: choosing between vector and raster

There is really one criterion: anything made of lines and text should be vector, anything with continuous tone should be raster. Vector images (PDF, EPS, SVG) describe points, lines and curves as coordinates, so the outlines are recomputed at any magnification and print resolution never enters into it. Plots, circuit diagrams and drawings carrying equations belong here. Raster images (PNG, JPEG) are a grid of coloured pixels; enlarge them and the pixels simply get bigger. Photographs and screenshots belong here, and for print you want source data at 300 dpi or more. Vectorising a photograph gains nothing and only bloats the file. When you generate a figure inside LaTeX — TikZ, pgfplots — the output is vector from the start.

Within raster, the rule of thumb is short: JPEG for photographs, PNG for everything else. JPEG is lossy and handles photographic gradation well, but it smears the edges of lines and letters with what is called mosquito noise — which is exactly why a screenshot saved as JPEG looks grubby around the text. PNG is lossless, supports transparency, and suits flat-colour graphics and screenshots. As for SVG, no engine reads it directly. The svg package lets you write \includesvg{file}, but behind the scenes it calls Inkscape's command line to convert to PDF (or to EPS for DVI output) and exports the text inside the SVG to a separate file that LaTeX re-typesets. It needs Inkscape installed and a compile with --shell-escape. If you want reliability, export to PDF up front with Inkscape or a similar tool. In the other direction, when you want SVG out of TeX output, dvisvgm is the tool.

Which formats each engine reads — and whether EPS really fails

What decides the accepted formats is not the engine but the driver file behind it. At startup graphics.cfg works out which engine is running and loads pdftex.def for pdfTeX, xetex.def for XeTeX, dvips.def for DVI output; whatever extension list that file declares is exactly the set of supported formats. Two corrections to the usual story follow from this. First, XeLaTeX and dvipdfmx handle EPS and PS directly: the extension lists in xetex.def and dvipdfmx.def contain .eps and .ps, and go on to .ai, .bmp and .jp2 as well. Second, pdfLaTeX and LuaLaTeX read EPS too, for all practical purposes.

The mechanism by which pdfLaTeX gets EPS through is written inside pdftex.def. At \begin{document}, if shell escape is enabled, that file appends .eps to the extension list itself and loads epstopdf-base. And the restricted shell escape that TeX Live enables by default is enough — no --shell-escape required. In restricted mode the safe twin repstopdf is called; only with --shell-escape does it switch to epstopdf proper. The converted file is left beside your source under the name myfig-eps-converted-to.pdf. pdftex.def attaches its own warning, though: when the PDF rather than the EPS is the real original, this automatic conversion can produce the wrong result. To switch it off, write \newcommand{\DoNotLoadEpstopdf}{} before the \documentclass line.

% EPS under pdflatex already works; this line only makes it explicit
\usepackage{epstopdf}

% ... and this, placed BEFORE \documentclass, switches the conversion off
% \newcommand{\DoNotLoadEpstopdf}{}

% pLaTeX / upLaTeX: the driver cannot be detected, so name it
% \usepackage[dvipdfmx]{graphicx}

There is also a reason not to lean on that automatic conversion. Run pdflatex -no-shell-escape and .eps never joins the extension list, so myfig.eps sitting right there still yields ! LaTeX Error: File 'myfig' not found. Worse is the case where you did write the extension: \includegraphics{myfig.eps} then produces neither an error nor a warning and quietly sets a framed box with the filename in it instead of the picture. Where a build server or a co-author's toolchain uses -no-shell-escape, the safe move is to convert EPS to PDF in advance and commit the PDF. For pLaTeX / upLaTeX, whose driver cannot be detected, state it: \usepackage[dvipdfmx]{graphicx}. When dimension data for a PNG, JPEG or PDF is needed, extractbb generates the .xbb sidecar.

When LaTeX says File not found

Errors around images say what is wrong in so many words. Four of them cover almost every mishap. ! LaTeX Error: File 'plot' not found. means “nothing matched under any extension in the list” — a typo, a missing \graphicspath, or an EPS-only figure with shell escape turned off. ! Package pdftex.def Error: File 'plot.png' not found: using draft setting. means “that one file is missing”. ! LaTeX Error: Unknown graphics extension: .tiff. means “the file exists, but this route does not know the format” — which is what you get from handing it a TIFF or a WebP. Convert to PNG or PDF.

The fourth has a different character. ! LaTeX Error: Cannot determine size of graphic in plot.png (no BoundingBox). means “the file was readable, but its dimensions are unknown”. You do get it from an EPS whose BoundingBox line is missing, but in daily work the overwhelming reason is having run latex when you meant pdflatex. latex goes down the DVI route, so dvips.def is loaded, and it cannot read the bytes of a PNG or JPEG as dimensions. If every figure breaks at once, suspect the compile command first.

• EPS BoundingBox: a missing line or wrong values leave the size undetermined. Rewrite it with ps2eps or epstool.
• Multi-page PDF: only page 1 by default. Pick a page with page=; to drop in a whole document, use the pdfpages package.
• Whitespace in a PDF: wide margins in a figure PDF make it look small. Trim them with pdfcrop before including it.
• Spaces and dots in filenames: names like my plot.tar.gz make the extension hard to split off. Stay with letters, digits, hyphens and underscores.
• Hard-coding the extension: naming the extension blocks swapping formats later. As a rule, write the name without it.

Finally, note that \includegraphics only drops the picture where it stands: it adds no number and no caption. To write “see Figure 3” in a paper you put the picture inside a figure environment and give it \caption and \label. Everything after that — where [htbp] actually lands the figure, how to style the caption, how to split it into (a) and (b) — is the business of this page's two companions.