nvim-lint
April 9, 2026 · View on GitHub
An asynchronous linter plugin for Neovim (>= 0.9.5) complementary to the built-in Language Server Protocol support.
Motivation & Goals
With ale we already got an asynchronous linter, why write yet another one?
Because ale also includes its own language server client.
nvim-lint instead has a more narrow scope: It spawns linters, parses their
output, and reports the results via the vim.diagnostic module.
nvim-lint complements the built-in language server client for languages where
there are no language servers, or where standalone linters provide better
results.
Installation
- Requires Neovim >= 0.9.5
nvim-lintis a regular plugin and can be installed via the:h packagesmechanism or via a plugin manager.
For example:
git clone \
https://github.com/mfussenegger/nvim-lint.git
~/.config/nvim/pack/plugins/start/nvim-lint
- If using vim-plug:
Plug 'mfussenegger/nvim-lint' - If using packer.nvim:
use 'mfussenegger/nvim-lint'
Usage
Configure the linters you want to run per file type. For example:
require('lint').linters_by_ft = {
markdown = {'vale'},
}
To get the filetype of a buffer you can run := vim.bo.filetype.
The filetype can also be a compound filetype. For example, if you have a buffer
with a filetype like yaml.ghaction, you can use either ghaction, yaml or
the full yaml.ghaction as key in the linters_by_ft table and the linter
will be picked up in that buffer. This is useful for linters like
actionlint in combination with vim.filetype patterns like
[".*/.github/workflows/.*%.yml"] = "yaml.ghaction",
Then setup a autocmd to trigger linting. For example:
au BufWritePost * lua require('lint').try_lint()
or with Lua auto commands:
vim.api.nvim_create_autocmd({ "BufWritePost" }, {
callback = function()
-- try_lint without arguments runs the linters defined in `linters_by_ft`
-- for the current filetype
require("lint").try_lint()
-- You can call `try_lint` with a linter name or a list of names to always
-- run specific linters, independent of the `linters_by_ft` configuration
require("lint").try_lint("cspell")
end,
})
Some linters require a file to be saved to disk, others support linting stdin
input. For such linters you could also define a more aggressive autocmd, for
example on the InsertLeave or TextChanged events.
If you want to customize how the diagnostics are displayed, read :help vim.diagnostic.config.
Security
Some linters prioritize using an executable relative to the current working
directory over the executable in $PATH. For example the eslint linter will
use ./node_modules/.bin/eslint if it exists. The executable is executed with
your users permission. Because of that, you must not call try_lint() in
untrusted repositories.
Available Linters
There is a generic linter called compiler that uses the makeprg and
errorformat options of the current buffer.
Other dedicated linters that are built-in are:
Custom Linters
You can register custom linters by adding them to the linters table, but
please consider contributing a linter if it is missing.
require('lint').linters.your_linter_name = {
cmd = 'linter_cmd',
stdin = true, -- or false if it doesn't support content input via stdin. In that case the filename is automatically added to the arguments.
append_fname = true, -- Automatically append the file name to `args` if `stdin = false` (default: true)
args = {}, -- list of arguments. Can contain functions with zero arguments that will be evaluated once the linter is used.
stream = nil, -- ('stdout' | 'stderr' | 'both') configure the stream to which the linter outputs the linting result.
ignore_exitcode = false, -- set this to true if the linter exits with a code != 0 and that's considered normal.
env = nil, -- custom environment table to use with the external process. Note that this replaces the *entire* environment, it is not additive.
parser = your_parse_function
}
Instead of declaring the linter as a table, you can also declare it as a function which returns the linter table in case you want to dynamically generate some of the properties.
your_parse_function can be a function which takes three arguments:
outputbufnrlinter_cwd
The output is the output generated by the linter command.
The function must return a list of diagnostics as specified in :help diagnostic-structure.
You can override the environment that the linting process runs in by setting
the env key, e.g.
env = { ["FOO"] = "bar" }
Note that this completely overrides the environment, it does not add new
environment variables. The one exception is that the PATH variable will be
preserved if it is not explicitly set.
You can generate a parse function from a Lua pattern, from an errorformat
or for SARIF using the functions in the lint.parser module:
for_sarif
parser = require("lint.parser").for_sarif()
The function takes an optional argument:
skeleton: Default values for the diagnostics
from_errorformat
parser = require('lint.parser').from_errorformat(errorformat)
The function takes two arguments: errorformat and skeleton (optional).
from_pattern
Creates a parser function from a pattern.
parser = require('lint.parser').from_pattern(pattern, groups, severity_map, defaults, opts)
pattern
The function allows to parse the linter's output using a pattern which can be either:
- A Lua pattern. See
:help lua-pattern. - A LPEG pattern object. See
:help vim.lpeg. - A function (
fun(line: string):string[]). It takes one parameter - a line from the linter output and must return a string array with the matches. The array should be empty if there was no match.
groups
The groups specify the result format of the pattern. Available groups:
lnumend_lnumcolend_colmessagefileseveritycode
The order of the groups must match the order of the captures within the pattern. An example:
local pattern = '[^:]+:(%d+):(%d+):(%w+):(.+)'
local groups = { 'lnum', 'col', 'code', 'message' }
The captures in the pattern correspond to the group at the same position.
severity
A mapping from severity codes to diagnostic codes
default_severity = {
['error'] = vim.diagnostic.severity.ERROR,
['warning'] = vim.diagnostic.severity.WARN,
['information'] = vim.diagnostic.severity.INFO,
['hint'] = vim.diagnostic.severity.HINT,
}
defaults
The defaults diagnostic values
defaults = {["source"] = "mylint-name"}
opts
Additional options
lnum_offset: Added tolnum. Defaults to 0end_lnum_offset: Added toend_lnum. Defaults to 0end_col_offset: offset added toend_col. Defaults to-1, assuming that the end-column position is exclusive.
Customize built-in linters
You can import a linter and modify its properties. An example:
local phpcs = require('lint').linters.phpcs
phpcs.args = {
'-q',
-- <- Add a new parameter here
'--report=json',
'-'
}
Some linters are defined as function for lazy evaluation of some properties. In this case, you need to wrap them like this:
local original = require("lint").linters.terraform_validate
require("lint").linters.terraform_validate = function()
local linter = original()
linter.cmd = "my_custom"
return linter
end
You can also post-process the diagnostics produced by a linter by wrapping it.
For example, to change the severity of all diagnostics created by cspell:
local lint = require("lint")
lint.linters.cspell = require("lint.util").wrap(lint.linters.cspell, function(diagnostic)
diagnostic.severity = vim.diagnostic.severity.HINT
return diagnostic
end)
Display configuration
See :help vim.diagnostic.config.
If you want to have different settings per linter, you can get the namespace
for a linter via require("lint").get_namespace("linter_name"). An example:
local ns = require("lint").get_namespace("my_linter_name")
vim.diagnostic.config({ virtual_text = true }, ns)
Get the current running linters for your buffer
You can see which linters are running with require("lint").get_running().
To include the running linters in the status line you could format them like this:
local lint_progress = function()
local linters = require("lint").get_running()
if #linters == 0 then
return ""
end
return " " .. table.concat(linters, ", ")
end
Alternatives
Development ☢️
Run tests
Running tests requires busted.
busted spec/
Or with luarocks:
luarocks test
If you get an error like:
E5113: Error while calling lua chunk: ...uarocks/lib/luarocks/rocks-5.1/busted/2.2.0-1/bin/busted:3: module 'busted.runner' not found:
no field package.preload['busted.runner']
You need to run eval $(luarocks path --no-bin) first.
See also:
- neorocks
- Using Neovim as Lua interpreter with Luarocks for installation instructions.
Docs
API docs is generated using vimcats:
vimcats -t -f lua/lint.lua lua/lint/parser.lua > doc/lint.txt