_{Catppuccin Icons in neo-tree.nvim}

real-icons.nvim brings real file and folder icons from PNG and SVG themes to explorers, pickers, statuslines, and tablines. It renders through the Kitty Graphics Protocol in Ghostty and Kitty, works through configured tmux passthrough, and safely falls back to glyphs in other terminals.

Why real-icons?

• No patched font is required for image rendering.
• SVG icons are converted once and cached automatically.
• Unsupported terminals keep working through mini.icons or nvim-web-devicons fallback.
• Directory rules can match full project paths without hardcoded framework behavior.

Quick start

Requirements

• Neovim 0.10+
• Ghostty or Kitty for image rendering
• magick from ImageMagick for SVG themes
• curl and tar for installing Material Icon Theme
• termguicolors

lazy.nvim

{
  "Mirsmog/real-icons.nvim",
  build = ":RealIcons install",
  opts = {
    integrations = {
      neo_tree = true,
    },
  },
}

Replace neo_tree with any integration key from the table below, or enable several.

To verify the renderer immediately:

:RealIcons demo

If Material Icon Theme is unavailable, the plugin uses its bundled fallback pack, so installation never leaves Neovim without icons.

One command

:RealIcons

With no arguments, :RealIcons opens a small menu. The same actions are available as subcommands for configuration and scripts:

Tab completion is available for every action. The standard command :checkhealth real-icons works as well.

Integrations

All integrations are opt-in. Add the matching key under integrations:

For example, an fzf-lua and Oil setup only needs:

require("real-icons").setup({
  integrations = {
    fzf_lua = true,
    oil = true,
  },
})

Integrations preserve sorting, filtering, git status, diagnostics, and other UI behavior.

require("telescope").setup({
  extensions = {
    file_browser = {
      entry_maker = require("real-icons.integrations.telescope_file_browser").entry_maker,
    },
  },
})

require("telescope").load_extension("file_browser")

More integration details are available in doc/real-icons.txt and :help real-icons-integrations.

Icon packs

Material Icon Theme is the recommended pack and is installed by the lazy.nvim build command shown above. The small builtin pack is always available.

Run this to browse every configured pack and compatible VS Code theme found on your machine:

:RealIcons packs

The picker scans the standard extension directories for VS Code, VSCodium, Cursor, and Windsurf, and previews each theme before switching.

require("real-icons").setup({
  pack = "my_theme",
  packs = {
    my_theme = {
      type = "vscode",
      path = "/path/to/vscode-icon-theme",
      theme = "theme-id",
    },
  },
})

Simple local packs, per-file overrides, and the pack loader API are documented under :help real-icons-packs.

Configuration

Most setups only need integration keys. The defaults reserve two terminal cells for one icon and automatically cache the correct size and color variant.

require("real-icons").setup({
  rules = {
    directories = {
      {
        glob = "**/packages/*/src/**",
        icon = "folder-packages",
      },
    },
  },
})

The complete option reference, including size, color, pack, and override settings, lives in doc/real-icons.txt. Inside Neovim, run :help real-icons-setup.

Terminal support

set -g allow-passthrough on

WezTerm supports the base Kitty Graphics Protocol but not the Unicode placeholders used to anchor images to Neovim cells. Until wezterm/wezterm#986 lands, backend = "auto" selects glyph fallback there.

Troubleshooting

Start with:

:RealIcons health

It checks Neovim, the terminal, termguicolors, ImageMagick, tmux passthrough, the selected icon pack, and enabled integrations.

If icons do not appear:

1. Run :RealIcons demo to isolate the renderer from integrations.
2. Run :RealIcons install if Material Icon Theme is missing.
3. Confirm magick is executable for SVG themes.
4. If tmux is active, confirm allow-passthrough is enabled.
5. Use :RealIcons clear-cache only if generated files are damaged or stale.

When reporting a problem, include the Neovim version, terminal name, plugin version, and output from :checkhealth real-icons.

How it works

1. A filename or directory path resolves to an image in the active icon pack.
2. SVG sources are rasterized once into a size and color-aware PNG cache.
3. The PNG is uploaded with Kitty Graphics Protocol.
4. A Unicode placeholder keeps the image attached to its Neovim grid cell.

The placeholder moves with the text grid, so integrations use normal text positions instead of absolute pixel coordinates.

Documentation and development

The help file covers the full configuration, Lua API, pack format, and adapter contracts:

:help real-icons

Run the local test suite with:

make test

Credits

• Neovim for the editor and UI primitives.
• Kitty Graphics Protocol for terminal image rendering.
• Material Icon Theme for the recommended icon pack.
• Catppuccin Icons and Flow Icons for themes shown in the previews.
• Ghostty and Kitty for implementing Unicode image placeholders.

License

real-icons.nvim is licensed under the MIT License. Installed icon packs keep their upstream licenses.

If real-icons.nvim makes your setup better, consider giving the project a star.