How do I customize the sign column and line number display with a single expression in Neovim?

Explanation

Neovim 0.9+ adds the statuscolumn option, which gives you a single statusline-style expression to control the entire left gutter — signs, line numbers, fold indicators, and anything else — in one place. Before this option, signs, numbers, and folds each had their own separate settings and couldn't be reordered or combined arbitrarily.

How it works

The value of statuscolumn is evaluated per-line using the same format items as statusline, plus some gutter-specific ones:

• %s — sign column (LSP diagnostics, git markers, etc.)
• %l — absolute line number (same as v:lnum)
• %r — relative line number
• %= — separate left from right alignment within the column
• %f — fold depth indicator (shows + on folded lines)
• %{expr} — embed any Vimscript expression

Example

Put signs on the left, then right-align the absolute line number:

:set statuscolumn=%s%=%l\ 

Or use Lua for a richer gutter with relative/absolute numbers that switch on focus:

vim.opt.statuscolumn = "%=%{v:relnum?v:relnum:v:lnum}%s"

This shows relative numbers for all lines except the cursor line, which shows the absolute number.

Tips

• Set statuscolumn in a WinEnter/WinLeave autocmd to show different gutters in focused vs unfocused windows
• Combine with numberwidth to control the minimum width of the number field
• Libraries like statuscol.nvim build on this option to provide pre-built gutter layouts with fold indicators and git signs
• Requires Neovim 0.9 or later; has no equivalent in Vim