Error rendering PDF with GIF images

[juliohm]

I have:

• searched the issue tracker for similar issues
• installed the latest version of Quarto CLI
• formatted my issue following the Bug Reports guide

Bug description

The following error message is displayed when attempting to render a PDF with GIF images:

Rendering PDF
running lualatex - 1
  This is LuaHBTeX, Version 1.18.0 (TeX Live 2024) 
   restricted system commands enabled.
  
  luaotfload | db : Font names database not found, generating new one.
  luaotfload | db : This can take several minutes; please be patient.
updating tlmgr

updating existing packages
ERROR: 
compilation failed- error
LaTeX Error: Unknown graphics extension: .gif.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.559 ...t,keepaspectratio]{images/juliahearts.gif}}

You can find the GIF insertion code here: https://github.com/JuliaEarth/geospatial-data-science-with-julia/blob/9a366081c857ab654fac88dcb71cc6f45a674e15/preface.qmd#L160

Steps to reproduce

git clone https://github.com/JuliaEarth/geospatial-data-science-with-julia
quarto render --to pdf

Actual behavior

An error message, no PDF output.

Expected behavior

PDF output with GIF image converted into a static image.

Your environment

VSCode
Version: 1.117.0
Commit: 10c8e557c8b9f9ed0a87f61f1c9a44bde731c409
Date: 2026-04-21T16:12:14-07:00
Electron: 39.8.7
ElectronBuildId: 13841579
Chromium: 142.0.7444.265
Node.js: 22.22.1
V8: 14.2.231.22-electron.0
OS: Linux x64 5.15.202-1-MANJARO

Quarto check output

Quarto 1.9.37
[✓] Checking environment information...
      Quarto cache location: /home/juliohm/.cache/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.8.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.4.5: OK
      Typst version 0.14.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.9.37
      Path: /opt/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: v2025.02
      Chromium: (not installed)
      Chrome Headless Shell: (not installed)
      VeraPDF: (not installed)

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /home/juliohm/.TinyTeX/bin/x86_64-linux
      Version: 2024

[✓] Checking Chrome Headless....................OK
      Using: Chrome from QUARTO_CHROMIUM
      Path: /usr/bin/chromium

[✓] Checking basic markdown render....OK

[✓] Checking R installation...........OK
      Version: 4.5.3
      Path: /usr/lib64/R
      LibPaths:
        - /usr/lib/R/library
      knitr: (None)
      rmarkdown: (None)

      The knitr package is not available in this R installation.
      Install with install.packages("knitr")
      The rmarkdown package is not available in this R installation.
      Install with install.packages("rmarkdown")

[✓] Checking Python 3 installation....OK
      Version: 3.14.3
      Path: /usr/bin/python3
      Jupyter: 5.9.1
      Kernels: python3, julia-1.11, julia-1.10, julia-1.9

[✓] Checking Jupyter engine render....OK

[✓] Checking Julia installation...

[cderv]

Thanks for the report.

I can reproduce with a minimal Quarto document containing a single .gif and format: pdf — no Julia required. The error comes from the LaTeX engine itself (same with pdflatex, lualatex, or xelatex):

LaTeX Error: Unknown graphics extension: .gif.

Where the gap is

1. LaTeX does not support .gif. graphicx accepts only the formats its driver knows about — png, jpg, pdf, jbig2 (and eps via auto-convert). No standard graphicx-compatible package adds .gif. Multimedia packages like media9 exist but use a different syntax and depend on the PDF reader to play the file, so they are not a drop-in for \includegraphics.

2. Quarto does not pre-convert images in its PDF pipeline. Quarto only produces the .tex from Pandoc and runs the LaTeX engine itself, so the image path reaches LaTeX unchanged: \includegraphics{…gif}.

3. Only SVG has a pre-conversion step in Quarto, done by this filter:

   https://github.com/quarto-dev/quarto-cli/blob/beb64f8a0ec6ac74906283e74cb168f5b4cbfdfc/src/resources/filters/quarto-post/pdf-images.lua

   It matches .svg only, no fallback for other formats.

4. Pandoc does have a fallback for unknown formats, but only when Pandoc itself drives the LaTeX engine (pandoc --pdf-engine=lualatex …) — which is not the case in Quarto's pipeline. The relevant code is convertImage in src/Text/Pandoc/PDF.hs:

   -- Convert formats which do not work well in pdf to png
   convertImage opts tmpdir fname = do
     ...
     case mime of
       Just "image/png"        -> doNothing
       Just "image/jpeg"       -> doNothing
       Just "application/pdf"  -> doNothing
       Just "application/eps"  -> doNothing
       Just "image/svg+xml"    -> (rsvg-convert -f pdf)
       _ -> JP.readImage fname >>= JP.savePngImage  -- e.g. .gif → .png

   We could consider mirroring this fallback in Quarto's pdf-images.lua so unknown formats are converted before LaTeX sees them.

5. That said, the current expectation in Quarto is that users provide format-appropriate inputs, and that computation engines emit the right cell output for the target format. So the recommended path today is to handle the conversion in your document or your code.

What you can do today

• Convert the GIF to PNG outside the rendering pipeline (e.g. magick image.gif image.png) and reference the PNG. PDFs are static — Pandoc's own path also keeps only the first frame.
• Have the computation emit a format-appropriate image at render time, conditional on the output format. On the Julia side, ImageMagick.jl is probably the most direct fit (binds libMagick, handles GIF read + PNG write). FileIO and Images work too — they end up calling ImageMagick under the hood for GIF. The cell would write PNG when targeting PDF and the original GIF for HTML.

For the conditional output approach, QUARTO_EXECUTE_INFO exposes the target format to the executing engine, in any language. Julia equivalent:

```{julia}
using JSON, FileIO, ImageMagick
execute_info = JSON.parsefile(ENV["QUARTO_EXECUTE_INFO"])
is_pdf = execute_info["format"]["identifier"]["base-format"] == "pdf"

img_path = is_pdf ? "image.png" : "image.gif"
if is_pdf && !isfile(img_path)
    save(img_path, load("image.gif"))
end
img_path
```

To be adapted from how the GIF is created. See #13514 for engine-agnostic documentation context, with R and Python examples.

Hope this clarifies the current behavior.

[juliohm]

Hi @cderv, thank you for the detailed reply. It is very informative.

Do you plan to provide a workaround or this conversion from GIF to static format needs to be handled by Quarto users? I thought that we could be agnostic to the output format, but I can understand the challenges involved.

Alternatively, is there a method to include images with a conditional statement that is based on the output format? I could store image.gif and image.png in the repository and try something along the lines of

if QUARTO_OUTPUT == PDF
  ![](images/image.png)
elseif QUARTO_OUTPUT == HTML
  ![](images/image.gif)
end

[cderv]

Oh yes for that there is a special syntax
See https://quarto.org/docs/authoring/conditional.html

Do you plan to provide a workaround or this conversion from GIF to static format needs to be handled by Quarto users? I thought that we could be agnostic to the output format, but I can understand the challenges involved.

This would require choosing a conversion library, and do best effort. .gif won't be support in LaTeX so one need to convert. If the user do the conversion, then it offers more control that if we do a default one. So I don't know, I need to think about this.

Also, it is possibly that typst has handling for gif directly https://typst.app/docs/reference/visualize/image/#parameters-format
and quarto now offers Typst book for PDF output: https://quarto.org/docs/books/book-output.html#typst-output

[juliohm]

Nice! I will try the conditional statement. Didn't know Quarto supported Typst, that is great! 🎉

[juliohm]

Just to double check, according to the docs we can

[![](images/juliahearts.gif){fig-alt="JuliaHearts" width=30px .content-visible when-format="html"}](https://julialang.org)

Is that right?

Trying to render in HTML now to see if it works.

[juliohm]

The attempt above failed with the same error. Could you please help with the syntax for the in-place conditional statement?

[mcanouil]

Your link is outside the conditional. What do you expect the link text to be when it's not HTML as the content is removed but not the link?

So, the issue is not really about the syntax.
As I have no idea of your intent, personally I would move the conditional attributes to the link level or even around it all via a div.

[juliohm]

The goal is to insert the GIF image only when the output format is HTML. The associated link should be inserted if the image is inserted. How to do that with the inline syntax? Do we need to add an extra div or paragraph?