Images and LaTeX previews

This file shows how org.nvim draws images in place of image links, and LaTeX formulas in place of their source, like Emacs' org-link-preview (C-c C-x C-v) and org-latex-preview (C-c C-x C-l).

Everything here is plain text first: an image link is [[file:x.png]] and a formula is $e^{i\pi} + 1 = 0$. A preview is only a picture drawn over that text by the terminal. Nothing in the file changes when you preview, so you can preview, hide and preview again as often as you like.

• The file starts folded (#+STARTUP: overview). Put the cursor on a heading and press <Tab> to open it; <S-Tab> cycles the whole buffer.
• u undoes any edit, and git checkout examples/21-images-latex.org restores the file.
• g? lists every key of the buffer.
• <prefix> means <leader>o (the default mappings.prefix). With examples/minimal_init.lua the leader is <Space>, so <prefix>xv is <Space>oxv.
• Emacs keys work too (:h org-emacs-keys): <C-c><C-x><C-v> is <prefix>xv, <C-c><C-x><C-l> is <prefix>xl.

Start Neovim from the repository root with the bundled init file, so your own config is not involved:

nvim -u examples/minimal_init.lua examples/21-images-latex.org

examples/minimal_init.lua only sets a leader key, agenda files, capture templates and a scratch org_directory; it leaves every image and LaTeX option at its default, which is what this file assumes.

Read "Before you start" first: previews need a terminal that can draw images. If yours can't, the file still teaches the syntax, and the section "No images? Pretty entities" gives you a text-only fallback.

A terminal is a grid of characters; drawing a picture in it needs a graphics protocol. org.nvim asks a backend to draw, chosen with ui.images.backend (default "auto", the first that works):

1. "native" (vim.ui.img): Neovim 0.13 or newer, in a terminal with the Kitty graphics protocol (kitty, Ghostty, WezTerm). Not through tmux.
2. "snacks": the image module of snacks.nvim. Works in tmux with set -g allow-passthrough on. Good for Neovim 0.11 and 0.12.
3. "image.nvim": the 3rd/image.nvim plugin.
4. none: no previews, and a message saying why.

Try: run :checkhealth org and scroll to the section "org.nvim image and LaTeX previews".

Expect: a line such as "Neovim 0.13.0 (has vim.ui.img), running directly in the terminal", then either "OK image backend: native" (or snacks / image.nvim), or a warning with advice. Below it, "LaTeX previews render with: dvipng" (or another process), or a note that no renderer is installed.

Things to know before pressing any key:

• Only PNG can be sent to the terminal. Other formats (JPEG, SVG, GIF…) are converted with ImageMagick (magick); without it you get "can't convert … to PNG".
• The first preview may pause for up to one second while org.nvim asks the terminal whether it speaks the Kitty protocol (in tmux nothing answers). Setting ui.images.backend to a name skips that question.
• An image is shown only when all of it fits in the window. Make the window tall enough (or :only) if a preview leaves blank rows.

A link is previewed when it points to an existing file whose extension is one of ui.images.extensions (png, jpg, jpeg, gif, webp, bmp, svg, tif, tiff, avif, xbm, xpm, pbm, pgm, ppm, pnm) and it has no description. The file path is relative to the directory of this file, so the pictures of the org.nvim demo live at ../docs/media/demo/img/.

An image link alone in its paragraph (nothing else on its line, no text line right above or below it) can be drawn left (default), centered or at the right, with :align or :center t on #+ATTR_ORG, or for every image with ui.images.align. Only the native backend (vim.ui.img) can do this; with snacks.nvim and image.nvim images stay left.

This line is part of the same paragraph as the link above.

Try: <prefix>xv on this heading (native backend, a wide window).

Expect: [current section] Displaying 4 images inline: a centered chart, a chart against the right edge of the text, a centered photo, and a last chart at the left.

The allowed values are left, center and right. Anything else is an error that :Org lint reports as invalid-image-alignment (see 22-extras.org).

ui.images.placement chooses where images are drawn:

"inline" (default)

the picture replaces the link: its top row is on the link's line at the link's column, the rest in blank rows under the line. Several images on one line sit side by side. On the cursor line the text shows again with the picture below it.

"below"

the picture is drawn under the line at the link's column, and the link text is left as it is (images of one line are stacked).

Two images and some text on one line: Before middle after.

Try: <prefix>xv on this heading. Then switch the placement and preview again:

:lua require("org.config").opts.ui.images.placement = "below"

and 64<prefix>xv followed by <prefix>xv here.

Expect: with "inline" the words "Before", "middle" and "after" are separated by the two pictures; with "below" the whole line of text stays readable and the two pictures are stacked under it. Set it back to "inline" afterwards.

Emacs' org-startup-with-inline-images and org-startup-with-latex-preview are the #+STARTUP: words:

The last word of a pair wins. The options ui.images.startup and ui.latex_preview.startup set the default for all files.

This file does not use them, so it opens fast and as text.

Try: change the first #+STARTUP: line of this file to

#+STARTUP: overview linkpreviews latexpreview

save with :w and reopen with :e.

Expect: the previewable links and (if a renderer is installed) the formulas are drawn as soon as you open their sections. Undo the change (u, :w) or git checkout the file afterwards.

With ui.images.cycle_display = true (Emacs org-cycle-link-previews-display), <Tab> takes care of the previews: showing an entry's children previews its own links, showing the whole subtree previews all of them, and folding it removes them.

Try:

:lua require("org.config").opts.ui.images.cycle_display = true

then fold everything with <S-Tab> (until OVERVIEW) and press <Tab> on the heading "Image links: which links get a picture" (once, then twice, then three times).

Expect: first nothing (that entry has no links of its own), then every picture of its subtrees, then none again when it folds.

http(s) links to an image file are not previewed by default. The option ui.images.remote (Emacs org-display-remote-inline-images) changes that:

"skip" (default)

never.

"download"

fetched with curl at every preview.

"cache"

fetched once into stdpath("cache")/org/remote-images, and again with <prefix>xV.

Try: with curl and ImageMagick installed and an internet connection:

:lua require("org.config").opts.ui.images.remote = "cache"

then <prefix>xv on this heading.

Expect: the Org unicorn logo (an SVG, converted to PNG). With the default "skip" the message is [current section] No images to display inline....

A link type can provide its own picture (Emacs org-link-set-parameters :preview). The function gets the link's path and returns an image file (or nil). For example, thumb:NAME links showing ~/thumbs/NAME.png:

require("org.ui.images").set_preview("thumb", function(path, ctx)
  return vim.fn.expand("~/thumbs/" .. path .. ".png")
end)

A preview function may also start a download and return true, then call ctx.callback(file) when the file is ready. The same function can be set as links.types.<type>.preview. See :h org.ui.images.set_preview().

A LaTeX fragment is math written inside the text. Org recognizes four delimiters, plus whole environments (next section). Every fragment below can be previewed with <prefix>xl; they are also exported as math to HTML (MathJax) and LaTeX (see 19-export.org).

A \begin{NAME} … \end{NAME} at the start of a line, with the \end line alone on its line, is an environment. It is rendered as a whole, like in a LaTeX document.

Maxwell's equations:

A numbered equation:

A matrix:

Try: <prefix>xl with the cursor on the \begin{align*} line.

Expect: Maxwell's two equations drawn as one aligned image. Then <prefix>xl on the heading: all three environments.

Environments are skipped inside source, example, export and comment blocks: the one below is code, not math.

\begin{equation}
  x = 1
\end{equation}

<prefix>xl works like <prefix>xv:

In Visual mode it renders the fragments of the selected lines. The ex forms are :[range]Org latex_preview [N] and :[range]Org clear_latex_preview.

Rendering runs in the background: the messages Creating LaTeX previews in buffer... and ... done. frame it, and Neovim stays usable meanwhile. Rendered images are kept, so previewing the same formula again is instant.

Try: 16<prefix>xl, wait for "done", then 64<prefix>xl.

Expect: every formula of the file drawn, then LaTeX previews removed from buffer and all text again.

Try: :%Org clear_latex_preview after rendering a few.

Expect: the same, without a message.

Editing a previewed fragment (or link) removes its preview: type inside one and the image disappears; preview it again when you are done.

Formulas are turned into images by real LaTeX programs, run by a process (ui.latex_preview.process, Emacs org-preview-latex-default-process). "auto" (default) uses the first one installed, in this order:

pdftocairo is part of poppler. A TeX Live or MacTeX install gives you latex and dvipng; tectonic (a single program that downloads the packages it needs) plus poppler is the lightest option.

Where the images go: ui.latex_preview.image_directory (default ltximg/ next to the file). Previewing a formula in this file creates examples/ltximg/; delete it when you are done (git status shows it). Set ui.latex_preview.cache_dir to one absolute directory to keep them all in one place.

Other options: scale (formula size, 1.0), foreground and background ("default" = the colors of the Normal text, "auto", a color, or "Transparent" for the background), header (the LaTeX preamble; the file's #+LATEX_HEADER: lines are added to it, so packages you load for export are there for previews too), and processes to add your own.

require("org").setup({
  ui = { latex_preview = { process = "tectonic", scale = 1.2, cache_dir = "~/.cache/ltximg" } },
})

When a step fails (a typo in a formula, a missing package), you get a warning and the program's output is in the buffer *Org Preview LaTeX Output*: open it with :b *Org Preview LaTeX Output*.

Try: <prefix>xl on the fragment below, which has an undefined command on purpose:

A broken formula: \(\notacommand{x}\)

Expect: a LaTeX preview: warning, no image, and LaTeX's "Undefined control sequence" in *Org Preview LaTeX Output*.

Without a graphics terminal you can still make math and symbols more readable with pretty entities (Emacs org-pretty-entities): \alpha shows as α, x^2 as x² and a_{ij} as aᵢⱼ, using Unicode characters. The text itself does not change.

• Greek: α, β, γ, π, Ω
• Arrows and relations: →, ⇒, ≤, ≥, ≠, ∞
• Superscripts and subscripts: x^2, e^-x, CO_2, a_ij
• Other entities: © 2026, 3×4, €5, …

Try: press <C-c><C-x>\ (toggle_pretty_entities).

Expect: the list above shows α, β, γ, π, Ω, →, ⇒, ≤, ≥, ≠, ∞, x², e⁻ˣ, CO₂, aᵢⱼ, ©, ×, € and …. Press it again to see the source. Entities inside verbatim, code, blocks and links are left alone.

To turn it on for a file, use #+STARTUP: entitiespretty (and entitiesplain to turn it off); for every file set ui.pretty_entities = true. ui.use_sub_superscripts (true, "{}", false) decides whether x^2 needs braces (x^{2}).

Run :checkhealth org first: it tells which backend is used, what sits between Neovim and the terminal (tmux, zellij, SSH), and which LaTeX process was found. Then:

"no image backend" / "does not support the Kitty graphics protocol"

Neovim older than 0.13, a terminal without the protocol, or tmux / zellij in between. Install snacks.nvim or image.nvim, run Neovim outside tmux, or use kitty / Ghostty / WezTerm.

Nothing happens for a second on the first preview

the terminal query waiting for an answer. Set ui.images.backend (e.g. "snacks").

In tmux

vim.ui.img can't reach the terminal. Use snacks.nvim and add set -g allow-passthrough on to ~/.tmux.conf, or run Neovim outside tmux.

In zellij

no passthrough at all; no backend can draw.

Over SSH

works with native and snacks.nvim; the images, ImageMagick and the LaTeX programs must be on the machine running Neovim.

Blank rows under the link but no image

the image doesn't fully fit in the window, a floating window covers it, or the terminal ignored it. Scroll it into view or make the window taller.

Images centered or misplaced

:align needs the native backend.

"can't convert … to PNG"

install ImageMagick (magick).

Images vanished (screen cleared) or wrong size after a font change

<prefix>xV.

"no LaTeX renderer found" or "you need to install the programs"

install latex + dvipng, or tectonic + poppler.

A formula stays text

check the $...$ rules above, and look at *Org Preview LaTeX Output*.

:h org-images

every option, key and command of this file.

:h org-images-troubleshooting

terminals, tmux, backends.

:h org.ui.images.set_preview()

custom preview functions.

:h org-appearance

pretty entities, ui options.

:h org-links and :h org-attach

links and attachment directories (also 13-links.org).

:h org-lint

invalid-image-alignment and other checks (22-extras.org).

:h org-export

how images and formulas are exported (19-export.org).