tomllint

A TOML Linter. Checks for basic syntactic errors in any TOML file.

Installation

$ pip install tomllint

Usage

Usage is self explanatory: name one or more files to lint, or use - as the sole filename to read from stdin.

usage: tomllint [-h] [--verbose] toml_file [toml_file ...]

positional arguments:
  toml_file      TOML filenames or "-" for stdin

options:
  -h, --help     show this help message and exit
  --verbose, -v  emit an info diagnostic for each file that lints successfully

By default tomllint is silent on success and only reports errors. Pass --verbose/-v to also emit a compiler-style filename:1:1: info: linted successfully line (on stderr) for each file that lints cleanly.

Release artifacts include a tomllint(1) manual page. System package installations and modern pipx installations expose it through man tomllint. A virtual-environment installation places it under that environment's share/man/man1, which may not be on MANPATH.

Neovim Integration

To register tomllint with nvim-lint, you'd add something like this to your ~/.config/nvim/init.lua or other imported file.

require("lint").linters_by_ft.toml = { "tomllint" }
local function parse_tomllint_output(output, bufnr, _linter_cwd)
	local diagnostics = {}
	for line in output:gmatch("[^\r\n]+") do
		local _, lnum, col, description = line:match("(.+):(%d+):(%d+): error: (.+)")
		if lnum and description then
			table.insert(diagnostics, {
				bufnr = bufnr,
				lnum = tonumber(lnum) - 1,
				col = tonumber(col) - 1,
				end_lnum = tonumber(lnum) - 1,
				end_col = tonumber(col),
				severity = vim.diagnostic.severity.ERROR,
				message = description,
			})
		end
	end
	return diagnostics
end
require("lint").linters.tomllint = {
	cmd = "tomllint",
	stdin = true,
	append_fname = false,
	args = { "-" },
	stream = "stderr",
	ignore_exitcode = false,
	env = nil,
	parser = parse_tomllint_output,
}

Pickls Integration

Pickls is a unified LSP that integrates command-line linters and formatters with editors like Neovim and Zed. Add the following to your ~/.config/pickls/pickls.yaml:

languages:
  toml:
    linters:
      - program: tomllint
        args: ["-"]
        pattern: '(.*):(\d+):(\d+): error: (.*)'
        line_match: 2
        start_col_match: 3
        description_match: 4
        use_stderr: true
        use_stdin: true

pre-commit Integration

pre-commit is a framework for managing and maintaining multi-language pre-commit hooks. To use tomllint to check your files when doing a git commit, add this to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/wbbradley/tomllint
    rev: v0.3.6
    hooks:
      - id: tomllint