imgpreview.nvim

Preview local image files inside Neovim using the Kitty graphics protocol.

Features

• Inline preview for the image path under the cursor
• Popup preview for the image path under the cursor
• Supports png, jpg, jpeg, webp, gif, bmp, tif, tiff, and avif

Requirements

• A terminal with Kitty graphics protocol support

Currently detected terminal setups include:

• Kitty
• Ghostty
• WezTerm
• tmux running inside Kitty, Ghostty, or WezTerm

For tmux, passthrough must be enabled:

set -g allow-passthrough on

If your terminal supports the protocol but is not detected automatically, you can set force_terminal_support = true.

Installation

vim.pack.add({
  { src = "https://github.com/Aethar01/imgpreview.nvim.git" },
})

require("imgpreview").setup()

Usage

Commands:

• :ImgPreview renders the image under the cursor inline
• :ImgPreviewPopup renders the image under the cursor in a popup
• :ImgPreviewClear clears any active preview
• :ImgPreviewDebug {path} renders a specific image for debugging

Lua:

local imgpreview = require("imgpreview")

imgpreview.render_hovered_inline()
imgpreview.render_hovered_popup()
imgpreview.clear()

Example mappings:

vim.keymap.set("n", "<leader>pi", function()
  require("imgpreview").render_hovered_inline()
end, { desc = "Preview image inline" })

vim.keymap.set("n", "<leader>pp", function()
  require("imgpreview").render_hovered_popup()
end, { desc = "Preview image popup" })

vim.keymap.set("n", "<leader>pc", function()
  require("imgpreview").clear()
end, { desc = "Clear image preview" })

Configuration

Default configuration:

require("imgpreview").setup({
  cell_width_to_height_ratio = 0.5,
  transport = "file",
  warn_on_unsupported_terminal = true,
  force_terminal_support = nil,
  inline = {
    max_width_cells = 40,
    max_height_rows = 18,
    min_width_cells = 12,
    position = "below",
    top_padding_rows = 0,
    gutter_padding = 0,
  },
  popup = {
    max_width_cells = 60,
    max_height_rows = 20,
    min_width_cells = 20,
    border = "rounded",
    position = "cursor",
    cursor_anchor = "bottom-left",
  },
  supported_extensions = {
    png = true,
    jpg = true,
    jpeg = true,
    webp = true,
    gif = true,
    bmp = true,
    tif = true,
    tiff = true,
    avif = true,
  },
})

Option reference:

Option	Type	Description
cell_width_to_height_ratio	number	Controls aspect-ratio correction from terminal cells to image pixels. Increase it if previews look too tall, decrease it if they look too short.
transport	"file"	Kitty graphics transport mode. Current implementation only uses file transport.
warn_on_unsupported_terminal	boolean	Shows a warning once when the current terminal does not appear to support the Kitty graphics protocol.
force_terminal_support	boolean | nil	Overrides terminal detection. Set to true to force-enable rendering, false to force-disable it, or nil to use auto-detection.
inline.max_width_cells	integer	Maximum inline preview width in terminal cells.
inline.max_height_rows	integer	Maximum inline preview height in terminal rows.
inline.min_width_cells	integer	Minimum inline preview width in terminal cells.
inline.position	"below"	Inline placement strategy. Current behavior renders the preview below the matched path.
inline.top_padding_rows	integer	Adds blank rows above the inline image.
inline.gutter_padding	integer	Adds extra horizontal spacing before the inline image.
popup.max_width_cells	integer	Maximum popup preview width in terminal cells.
popup.max_height_rows	integer	Maximum popup preview height in terminal rows.
popup.min_width_cells	integer	Minimum popup preview width in terminal cells.
popup.border	string	Border style passed to nvim_open_win() for the popup window, for example "rounded" or "single".
popup.position	"center" or "cursor"	Popup placement mode. Use "center" to center the preview on screen, or "cursor" to place it near the hovered image path.
popup.cursor_anchor	"bottom-left" or "center"	Preferred popup direction when popup.position = "cursor". "bottom-left" prefers rendering below and to the right of the cursor, while "center" first tries to center the popup around the cursor before falling back to nearby positions.
supported_extensions	table<string, boolean>	Map of allowed local image file extensions. Set an entry to false to disable it or add more extensions with true.