# numbers.vim: line numbers that follow the mode you are in

> myusuf3/numbers.vim swaps between relative and absolute numbering based on insert mode, Ex commands, window focus and editor focus. It is a small Vim script with a specific idea about when a line number is worth reading.

**myusuf3/numbers.vim** — numbers.vim is a vim plugin for better line numbers

- Repository: https://github.com/myusuf3/numbers.vim
- Stars: 744 · Forks: 48
- Language: Vim Script
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/myusuf3-numbers-vim

## The numbering mode follows your mode, not your config

Vim ships two mutually exclusive options for the gutter: `number` and `relativenumber`. Most people pick one at startup and never touch it again. numbers.vim takes a different approach and treats the choice as something that should change while you work, based on where your attention is.

The plugin alternates between relative numbering and absolute numbering for the active window depending on the mode you are in, and in a GUI it also reacts to whether the application itself has focus. The practical effect is that normal mode shows distances from the cursor line, which is what you want when you are moving with motions like `5j` or `gg`, while insert mode shows real line numbers so you can see the absolute position of the cursor in the file.

Numbers also go absolute while you are typing an Ex command, which the documentation explains with a concrete case: the line in `:14y` has to be readable off the gutter. The same absolute treatment applies in inactive windows and while the editor is unfocused, so background buffers do not display a relative scale that is meaningless when you are not working in them.

That is the whole idea in one paragraph, and it is a real design opinion rather than a generic convenience wrapper.

## Two filters decide which windows keep their numbers

A mode aware plugin is only useful if it stays out of the way, and the noisy case is plugin windows. The documentation calls this Numbers Don't Belong, and the mechanism is two separate exclusion lists keyed on different buffer properties.

The first list is keyed on filetype and is what most people configure. Setting it to a superset of the plugin default is the documented requirement:

```bash
    let g:numbers_exclude = ['unite', 'tagbar', 'startify', 'gundo', 'vimshell', 'w3m', 'nerdtree', 'Mundo', 'MundoDiff', 'buffergator', 'easybuffer']
```

The second list exists because filetype is not always available. The documentation points out that plugin windows often leave `filetype` empty, which puts them out of reach of a filetype based list, so those buffers are excluded by `buftype` instead:

```bash
    let g:numbers_exclude_buftypes = ['acwrite', 'help', 'nofile', 'nowrite', 'popup', 'prompt', 'quickfix', 'terminal']
```

The trade-off is explicit. That buftype list covers every special buffer kind by default, and the documentation tells you to shorten it if you want line numbers back in one of those windows. You are trading a clean gutter in plugin windows for control that is coarser than a per plugin list.

## Installing with pathogen or vundle

The plugin requires Vim 7.3 or newer. There is no package manager of its own and no build step, which matches how Vim plugins have traditionally been distributed. The documentation recommends pathogen or vundle.

For pathogen users, the plugin is cloned straight into the bundle directory:

```bash
    git clone https://github.com/myusuf3/numbers.vim.git ~/.vim/bundle/numbers
```

For vundle users, one line in the vimrc is enough, followed by running `:BundleInstall`:

```bash
    Bundle "myusuf3/numbers.vim"
```

Both paths leave the plugin loaded on startup with no action required on your part, according to the documentation. The repository layout backs this up. The top level entries are the LICENSE, the README, a doc folder, a plugin folder and a test folder, with a .github directory and a .gitignore on top, so the runtime surface is the plugin folder and the documentation lives separately in doc.

One thing to check before you install: the exclude list only works if you set it. If your vimrc has no `g:numbers_exclude` assignment, the plugin falls back to its built in default, which is a smaller list than many people expect.

## Commands and mappings for manual control

Automatic switching is the default behaviour, but the plugin also ships commands for toggling the numbering method and for enabling and disabling the plugin as a whole. These are useful when you are demonstrating a screen, when a screencast shows relative numbers to an audience who does not know how to read them, or when a plugin window misbehaves.

The documentation suggests adding mappings to your vimrc for convenience, with these two as the examples:

```bash
    nnoremap <F3> :NumbersToggle<CR>
    nnoremap <F4> :NumbersOnOff<CR>
```

The distinction between the two matters. NumbersToggle switches the numbering method, while NumbersOnOff turns the plugin on or off, which puts your gutter back under plain Vim control. Neither command needs arguments.

What the documentation does not say is much about edge cases around these commands, such as how they interact with a `set number` in your vimrc or with an autocommand of your own that also touches `relativenumber`. Anyone combining numbers.vim with a statusline or a colourscheme script that manages these options should expect to test that combination themselves.

## The test suite runs real editors per case

The repository carries a test directory with a shell runner, and the documentation describes it accurately enough that you can use it as a starting point for your own checks. Each case in `test/cases/` runs in its own editor process and asserts on `number` and `relativenumber`, so a failing toggle does not contaminate the next case.

The runner takes an optional case name:

```bash
    ./test/run.sh            # every case, against both vim and neovim
    ./test/run.sh toggle     # a single case
```

Two details matter for anyone trying this locally. The script exercises both vim and neovim, and editors that are not installed are skipped rather than failing, so a machine with only one of the two still runs a meaningful subset. Continuous integration runs the same script.

This matters more than it might appear for a plugin whose entire behaviour is the state of two options. Asserting on `number` and `relativenumber` per process is a reasonable way to pin down the mode switching contract, and it is the mechanism you would want to extend if you modify the plugin to handle a new mode.

## Where the plugin steps aside: VSCode and Vim 7.4

Two situations are called out in the documentation, and both are cases where adopting the plugin is the wrong call.

The first is VSCode. Under the vscode-neovim extension the plugin disables itself, because VSCode draws its own gutter, so switching `number` and `relativenumber` in Neovim has no effect on screen there. The documentation also notes that the plugin used to shift the cursor several columns to the right when entering insert mode in that setup. If your Neovim runs inside VSCode, this plugin is inert and the editor's own setting is the relevant one:

```json
    "editor.lineNumbers": "relative"
```

That setting is a different approach to the same problem. VSCode keeps one numbering mode for the editor session, while numbers.vim switches modes continuously and adds Ex command and focus awareness that a static editor setting does not attempt.

The second situation is Vim 7.4. The documentation warns that Vim 7.4 users may experience unexpected behaviour if `set number` is not present in your `~/.vimrc`. Since the plugin switches `number` and `relativenumber` itself, a vimrc that only sets one of the two can end up in a state the plugin does not expect.

## Release history: three versions in over a decade

The repository publishes GitHub releases, and the version history says something about where the project sits. The most recent release is v0.7.0, named Recount, dated 2026-08-01. The two before it are v0.6.1 (NERDTree) from 2013-10-10 and v0.6.0 (Turn up!) from 2013-09-15.

So the plugin sat at 0.6 for a long stretch and then moved to 0.7 in 2026. The version names track the subject matter, since NERDTree appears in both the default exclude list and the release title of v0.6.1, which is consistent with plugin windows needing special handling.

The last push was on 2026-08-01, the same date as the v0.7.0 release, so the current state of the repository matches the latest tagged version. The licence is MIT, which means the code can be reused and modified in a way that suits a personal or company configuration, with no copyleft obligation attached to the plugin source.

The gap between the old releases and the recent one also means the plugin's behaviour has not been continuously re-verified against every Vim release in between, so a version bump on your side is worth a look at the exclude lists.

## Conclusion

Use numbers.vim if you read and write Vim daily and keep typing in insert mode, where relative numbering is noise but absolute numbering tells you where you are. Skip it if you want one fixed numbering scheme, if you work mainly inside VSCode through the vscode-neovim extension, where the plugin disables itself, or if your workflow depends on `set number` in your vimrc on Vim 7.4. Before adopting, check that the exclude list in your config is a superset of the plugin default, and note that the last push was on 2026-08-01, which carried the v0.7.0 release.

## FAQ

### How do I stop numbers.vim from adding numbers to NERDTree and other plugin windows?

Set `g:numbers_exclude` in your vimrc to a superset of the plugin default, which already includes nerdtree, gundo, tagbar and others. Plugin windows with an empty filetype are excluded through `g:numbers_exclude_buftypes` instead.

### Which Vim versions does numbers.vim require?

The requirement listed is Vim 7.3 or newer. The documentation adds a caution for Vim 7.4 users, who may see unexpected behaviour if `set number` is missing from their `~/.vimrc`.

### Does numbers.vim work with Neovim and with VSCode?

The test runner exercises both vim and neovim, and editors that are not installed are skipped. Under the vscode-neovim extension the plugin disables itself, because VSCode renders its own gutter.

## Sources

- [Issues](https://github.com/myusuf3/numbers.vim/issues)
- [License: MIT](https://github.com/myusuf3/numbers.vim/blob/master/LICENSE)
- [myusuf3/numbers.vim on GitHub](https://github.com/myusuf3/numbers.vim)
- [README](https://github.com/myusuf3/numbers.vim/blob/master/README.md)
- [Releases](https://github.com/myusuf3/numbers.vim/releases)

---

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