# minimap.vim renders a code minimap by shelling out to a Rust binary

> minimap.vim draws a scrolling minimap of the buffer in a Vim split, but it does no drawing itself: a separate Rust program called code-minimap does the rendering and the plugin receives the result. That split explains the speed, and it also means the plugin has a binary dependency you must install separately.

**wfxr/minimap.vim** — 📡 Blazing fast minimap / scrollbar for vim, powered by code-minimap written in Rust.

- Repository: https://github.com/wfxr/minimap.vim
- Stars: 1,300 · Forks: 26
- Language: Vim Script
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/wfxr-minimap-vim

## The plugin is a viewer, code-minimap is the renderer

The architecture is the first thing to understand, and the README states it plainly. code-minimap is required, and the plugin receives the rendered minimap from it. The Rust binary does the work of turning buffer content into an image or text block that can be placed in a Vim window, and the Vim script side handles the split, the scrolling, the highlight and the commands. That is why the description calls the plugin blazing fast, and also why the requirement list is not just a Vim version. The plugin is a Vim script distribution with a native dependency, and the repository root shows that shape, with a plugin directory, an autoload directory, a bin directory, a doc directory and a t directory for tests. The Rust side lives in its own code-minimap repository, which is where the benchmark the README links to lives as well.

## Installation means two things, and the plugin manager can do both

The README gives the requirement list first: code-minimap has to be present, and you need vim8.2 or later, or neovim 0.5.0 or later. Then it says to use your favourite plugin manager, with vim-plug as the example.

```vim
Plug 'wfxr/minimap.vim'
```

For Rust users there is a variant that installs the helper at the same time, which the README recommends only for people who already use cargo.

```vim
Plug 'wfxr/minimap.vim', {'do': ':!cargo install --locked code-minimap'}
```

The do hook runs a cargo install for code-minimap with the lockfile pinned, so the helper version is fixed to what the plugin expects. If you use a different plugin manager, the README points at an issue with manual installation instructions for people who cannot use a plugin manager at all. Either way, the outcome is the same: a Vim plugin that will show a warning at startup if the helper is missing, unless you turn that warning off.

## Six commands, and what each one forces

The command table is small and each entry does something different from opening and closing. Minimap shows the minimap window, MinimapClose closes it and MinimapToggle toggles it. The three force commands are the interesting ones. MinimapRefresh forces a refresh of the minimap window, MinimapUpdateHighlight forces an update of the minimap highlight, and MinimapRescan forces a recalculation of the minimap scaling ratio. The scaling ratio is the mechanism behind dynamic scaling, the feature where the minimap keeps its proportions as the window width changes. Rescanning is what you need after a dramatic resize, and the distinction between the refresh and the highlight commands is that one repaints the content while the other only moves the highlight. Having separate force commands for those two is a small design decision that saves a full re-render in the common case.

## Dynamic scaling is what makes a text minimap usable at any width

The width of the minimap window is set in characters, `g:minimap_width`, with a default of 10, and the scaling logic is what decides how much of the buffer fits into that width. The scaling ratio is computed rather than fixed, so a long file is compressed to fit and a short file is not stretched absurdly. There is a cap for that calculation, `g:minimap_window_width_override_for_scaling`, whose default is 2147483647, which is effectively no cap at all, and the README refers to the minimap.txt help file for the details of how the cap affects the result. The point of the cap is to stop the minimap from scaling past the point where a single character represents an enormous span of the file, which would make the minimap misleading. It is the one option in the table whose correct value depends on how you read the help file rather than on a one line description.

## Highlight options cover the cursor, the search, the visible range and git changes

The highlight configuration is where the plugin gets its detail. `g:minimap_highlight_range` is on by default and highlights the range of visible lines, so you can see where you are in the file. `g:minimap_highlight_search` is off by default and highlights searched patterns. `g:minimap_git_colors` is off by default and highlights the range of changes as reported by git, which is a genuinely useful pairing with a diff-oriented workflow. The base colour group is set by `g:minimap_base_highlight`, defaulting to Normal, and the plugin sets its own colour groups to give a reasonable default, with separate priority values for the search highlight colours and the cursor highlight colours, 120 and 110 by default. Priorities matter here because the plugin creates its own colour groups, and if your colorscheme already defines highlights at a higher priority the minimap colours can be overridden. The plugin also creates an autocommand on colorscheme changes, controlled by `g:minimap_enable_highlight_colorgroup`, so the minimap follows your theme.

## Buffer type exclusions decide where the minimap appears at all

Four options control which buffers get a minimap, and they use different words on purpose. `g:minimap_block_filetypes` disables the minimap for specific file types, with a default list of fugitive, nerdtree, tagbar and fzf, all of which are plugin or filetype manager windows where a minimap of a diff or a file tree makes no sense. `g:minimap_block_buftypes` disables it for buffer types, defaulting to nofile, nowrite, quickfix, terminal and prompt, which are the special and transient buffers where a scrollable minimap is either meaningless or harmful. Then there are two more forgiving options. `g:minimap_close_filetypes` closes the minimap for specific file types, defaulting to startify, netrw and vim-plug, and `g:minimap_close_buftypes` does the same for buffer types with an empty default. The difference is that blocking prevents the window from appearing, while closing lets it exist and then removes it, which is the behaviour you want for a buffer you sometimes want to see the minimap of.

## Startup behaviour, the left-hand placement and the background process

Three remaining options are worth pulling out. `g:minimap_auto_start` shows the minimap at startup when set, and `g:minimap_auto_start_win_enter` shows it on WinEnter, but only if the auto start option is also set. `g:minimap_left` appends the minimap window to the left rather than the right. `g:minimap_exec_warning` enables the not found warning message at startup, which is on by default and is the message that tells you code-minimap was not found on your PATH. The one option with a real dependency behind it is `g:minimap_background_processing`, off by default, which makes the plugin use a background job to get the longest line, and that requires gnu-wc on MacOS. That last detail is the kind of thing that only shows up on one platform, and it explains why the option is not simply turned on.

## Maintenance state and a plugin with a compiled half

The repository is not archived, and the last push was on 2026-07-22. There are no GitHub releases, which is normal for a Vim plugin distributed through a plugin manager, where the plugin manager tracks the repository. The project is MIT licensed, with a LICENSE file at the root, and the repository carries an AGENTS.md and a CI workflow, so the Vim script is formatted and checked automatically. The pre-commit configuration is present too. What makes this repository different from a pure script plugin is the split of responsibilities: the Vim side is here, and the Rust renderer is in a separate code-minimap project. That means a bug in the rendering can be in either repository, and a version mismatch between the two is possible in principle, which is the argument for the cargo install variant with the lockfile pinned, since it keeps the two in step.

The example configuration in the README is three lines, and the width comes first.

```vim
let g:minimap_width = 10
let g:minimap_auto_start = 1
let g:minimap_auto_start_win_enter = 1
```

## Conclusion

minimap.vim suits a Vim or Neovim user who wants a live minimap of a long buffer and already accepts installing a compiled helper alongside the plugin. It does not suit a setup where shipping a binary with the plugin is not acceptable, since code-minimap is a required external component, and it does not suit a Vim older than 8.2 or a Neovim older than 0.5.0. Before you install it, get code-minimap on your PATH, and set `g:minimap_block_filetypes` and `g:minimap_block_buftypes` for the buffer types you never want a minimap in, because the defaults already exclude fugitive, nerdtree, tagbar, fzf and the quickfix and terminal buffers.

## FAQ

### What does minimap.vim need to work?

It needs the code-minimap binary, because the plugin receives the rendered minimap from it, and it needs vim 8.2 or later, or neovim 0.5.0 or later. The README shows a vim-plug entry that installs the helper with cargo.

### How do I install minimap.vim with vim-plug?

Add `Plug 'wfxr/minimap.vim'` to your plugin list. If you already use cargo, the README also shows `Plug 'wfxr/minimap.vim', {'do': ':!cargo install --locked code-minimap'}`, which installs the helper at the same time.

### How do I stop the minimap from appearing in plugin and special buffers?

Use `g:minimap_block_filetypes` and `g:minimap_block_buftypes`. The defaults already exclude fugitive, nerdtree, tagbar and fzf file types, and the nofile, nowrite, quickfix, terminal and prompt buffer types. There are separate `g:minimap_close_filetypes` and `g:minimap_close_buftypes` options that close the window rather than blocking it.

### Can minimap.vim highlight git changes and search matches?

Yes, both are off by default. `g:minimap_git_colors` highlights the range of changes as reported by git, and `g:minimap_highlight_search` highlights searched patterns, while `g:minimap_highlight_range` is on by default and marks the visible lines.

### What is the difference between MinimapRefresh and MinimapUpdateHighlight?

MinimapRefresh forces a refresh of the minimap window itself, while MinimapUpdateHighlight forces only the highlight to update. MinimapRescan is the third force command and recalculates the minimap scaling ratio, which is what you want after a large resize.

### How do I make the minimap wider in minimap.vim?

Set `g:minimap_width`, which is the width of the minimap window in characters and defaults to 10. The rendering scales to fit that width, and `g:minimap_window_width_override_for_scaling` caps how far the scaling may go, with the details in the minimap.txt help file.

## Sources

- [Issues](https://github.com/wfxr/minimap.vim/issues)
- [License: MIT](https://github.com/wfxr/minimap.vim/blob/master/LICENSE)
- [README](https://github.com/wfxr/minimap.vim/blob/master/README.md)
- [wfxr/minimap.vim on GitHub](https://github.com/wfxr/minimap.vim)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wfxr-minimap-vim