sixel-preview.nvim

Preview images and PDFs directly inside Neovim using Sixel graphics.

Built for Windows Terminal 1.22+, but works on any sixel-capable terminal (WezTerm, foot, mlterm, etc.).

Image Preview

PDF Preview

Features

• Image preview — PNG, JPG, GIF, SVG, WebP, BMP, TIFF, ICO
• PDF preview with page-by-page navigation (n/p/J/K)
• File explorer integration — auto-previews when you open an image/PDF from Snacks explorer, neo-tree, oil.nvim, etc.
• Dynamic sizing — detects your terminal's pixel dimensions and scales images to fit
• Render caching — in-memory cache with mtime-based invalidation
• Clean tab switching — sixel artifacts are cleared when you switch tabs, re-rendered when you return
• :checkhealth — verifies all dependencies and terminal support

Requirements

Dependency	Required	Notes
Neovim >= 0.9	Yes	0.10+ recommended
Sixel-capable terminal	Yes	Windows Terminal 1.22+, WezTerm, foot, mlterm
ImageMagick 7+	Yes	Must have sixel delegate (check with :checkhealth)
poppler-utils	For PDFs	Provides pdftoppm for fast PDF rasterization

Quick install (Windows)

# Using scoop
scoop install imagemagick
scoop install poppler

# Or using winget
winget install ImageMagick.ImageMagick

Quick install (Linux/macOS)

# Ubuntu/Debian
sudo apt install imagemagick poppler-utils

# macOS
brew install imagemagick poppler

Installation

lazy.nvim

-- lua/plugins/sixel-preview.lua
return {
  "truashamu/sixel-preview.nvim",
  event = "VeryLazy",
  cmd = { "SixelPreview", "SixelPreviewToggle", "SixelPreviewClose", "SixelPreviewPage" },
  keys = {
    { "<leader>sp", "<cmd>SixelPreviewToggle<cr>", desc = "Toggle sixel preview" },
    { "<leader>sP", "<cmd>SixelPreviewClose<cr>", desc = "Close sixel preview" },
  },
  opts = {},
}

Manual

Clone into your Neovim packages directory:

git clone https://github.com/truashamu/sixel-preview.nvim \
  ~/.local/share/nvim/site/pack/plugins/start/sixel-preview.nvim

Usage

Commands

Command	Description
:SixelPreview [file]	Preview a file (defaults to current buffer's file)
:SixelPreviewToggle	Toggle preview for current file
:SixelPreviewClose	Close the preview tab
:SixelPreviewPage 3	Jump to a specific PDF page
:SixelClearCache	Clear the render cache

PDF Navigation

When previewing a PDF, these buffer-local keybindings are active:

Key	Action
n / J	Next page
p / K	Previous page
q	Close preview

Auto-Preview

When auto_preview is enabled (the default), opening any supported file from a file explorer will automatically render it as sixel. Works out of the box with:

• Snacks explorer
• neo-tree
• oil.nvim
• Any plugin that triggers BufReadCmd

Configuration

These are the defaults — you only need to set what you want to change:

require("sixel-preview").setup({
  -- Conversion backends
  converters = {
    image = "magick",   -- "magick" (ImageMagick) or "chafa"
    pdf = "pdftoppm",   -- "pdftoppm" (poppler) or "magick"
  },

  -- Sixel output sizing (used as fallback when dynamic detection fails)
  sixel = {
    max_width = 800,
    max_height = 600,
    background = "none",  -- "none", "black", "white"
    cell_size = { 8, 16 }, -- fallback { width, height } in pixels per cell
  },

  -- PDF-specific
  pdf = {
    page = 1,     -- default starting page
    dpi = 150,    -- rasterization resolution
  },

  -- Auto-preview when opening supported files
  auto_preview = true,

  -- Tab behavior
  tab = {
    close_on_leave = false, -- close preview tab when switching away
    reuse = true,           -- reuse existing preview tab
    title = "Preview",      -- tab title prefix
  },

  -- Supported file types
  filetypes = {
    image = { "png", "jpg", "jpeg", "gif", "bmp", "webp", "tiff", "ico", "svg" },
    pdf = { "pdf" },
  },

  -- Binary overrides (if not on PATH)
  bin = {
    magick = "magick",
    pdftoppm = "pdftoppm",
    chafa = "chafa",
  },
})

Health Check

Run :checkhealth sixel-preview to verify your setup:

sixel-preview.nvim
- OK Neovim >= 0.9
- OK Running inside Windows Terminal (WT_SESSION detected)
- OK ImageMagick found: ImageMagick 7.1.2-Q16-HDRI
- OK ImageMagick has sixel support
- OK pdftoppm found (poppler-utils)

How It Works

1. File detection — extension mapped to converter type (image or PDF)
2. Conversion — ImageMagick converts to sixel format, writing to a temp file
3. Display — raw sixel escape sequences sent to the terminal via nvim_chan_send
4. Positioning — ANSI cursor positioning places the image inside the correct Neovim window
5. Caching — rendered sixel data cached in memory, keyed on filepath + mtime + dimensions

For PDFs: pdftoppm rasterizes a page to PNG → ImageMagick converts to sixel.

Dynamic Sizing

On Windows, the plugin detects terminal pixel dimensions via the Win32 GetForegroundWindow + GetClientRect API (through LuaJIT FFI). On Unix, it uses the standard TIOCGWINSZ ioctl. This means images and PDFs scale properly to your window size — no hardcoded dimensions.