Configuration file

luacheck tries to load configuration from .luacheckrc file in the current directory. If not found, it will look for it in the parent directory and so on, going up until it reaches file system root. Path to config can be set using --config option, in which case it will be used during recursive loading. Config loading can be disabled using --no-config flag.

If neither of --config, --no-config, and --no-default-config options are used, luacheck will attempt to load configuration from value of --default-config option, or %LOCALAPPDATA%\Luacheck\.luacheckrc on Windows, ~/Library/Application Support/Luacheck/.luacheckrc on OS X/macOS, and $XDG_CONFIG_HOME/luacheck/.luacheckrc or ~/.config/luacheck/.luacheckrc on other systems by default.

Config is simply a Lua script executed by luacheck. It may set various options by assigning to globals or by returning a table with option names as keys.

Options loaded from config have the lowest priority: it’s possible to overwrite them with CLI options or inline options.

Config options

Option

Type

Default value

color

Boolean

true

codes

Boolean

false

formatter

String or function

"default"

cache

Boolean or string

false

jobs

Positive integer

1

exclude_files

Array of strings

{}

include_files

Array of strings

(Include all files)

global

Boolean

true

unused

Boolean

true

redefined

Boolean

true

unused_args

Boolean

true

unused_secondaries

Boolean

true

self

Boolean

true

std

String or set of standard globals

"_G"

globals

Array of strings or field definition map

{}

new_globals

Array of strings or field definition map

(Do not overwrite)

read_globals

Array of strings or field definition map

{}

new_read_globals

Array of strings or field definition map

(Do not overwrite)

not_globals

Array of strings

{}

compat

Boolean

false

allow_defined

Boolean

false

allow_defined_top

Boolean

false

module

Boolean

false

max_line_length

Number or false

120

max_code_line_length

Number or false

120

max_string_line_length

Number or false

120

max_comment_line_length

Number or false

120

ignore

Array of patterns (see Patterns)

{}

enable

Array of patterns

{}

only

Array of patterns

(Do not filter)

inline

Boolean

true

An example of a config which makes luacheck ensure that only globals from the portable intersection of Lua 5.1, Lua 5.2, Lua 5.3 and LuaJIT 2.0 are used, as well as disables detection of unused arguments:

1std = "min"
2ignore = {"212"}

Custom sets of globals

std option allows setting a custom standard set of globals using a table. This table can have two fields: globals and read_globals. Both of them should contain a field definition map defining some globals. The simplest way to define globals is to list their names:

1std = {
2   globals = {"foo", "bar"}, -- these globals can be set and accessed.
3   read_globals = {"baz", "quux"} -- these globals can only be accessed.
4}

For globals defined like this Luacheck will additionally consider any fields within them defined. To define a global with a restricted set of fields, use global name as key and a table as value. In that table, fields subtable can contain the fields in the same format:

 1std = {
 2   read_globals = {
 3      foo = { -- Defining read-only global `foo`...
 4         fields = {
 5            field1 = { -- `foo.field1` is now defined...
 6               fields = {
 7                  nested_field = {} -- `foo.field1.nested_field` is now defined...
 8               }
 9            },
10            field2 = {} -- `foo.field2` is defined.
11         }
12      }
13   }
14}

Globals and fields can be marked read-only or not using read_only property with a boolean value. Property other_fields controls whether the global or field can also contain other unspecified fields:

 1std = {
 2   read_globals = {
 3      foo = { -- `foo` and its fields are read-only by default (because they are within `read_globals` table).
 4         fields = {
 5            bar = {
 6               read_only = false, -- `foo.bar` is not read-only, can be set.
 7               other_fields = true, -- `foo.bar[anything]` is defined and can be set or mutated (inherited from `foo.bar`).
 8               fields = {
 9                  baz = {read_only = true}, -- `foo.bar.baz` is read-only as an exception.
10               }
11            }
12         }
13      }
14   }
15}

Custom sets can be given names by mutating global stds variable, so that they can then be used in --std CLI option and std inline and config option.

1stds.some_lib = {...}
2std = "min+some_lib"

In config, globals, new_globals, read_globals, and new_read_globals can also contain definitions in same format:

 1read_globals = {
 2   server = {
 3      fields = {
 4         -- Allow mutating `server.sessions` with any keys...
 5         sessions = {read_only = false, other_fields = true},
 6         -- other fields...
 7      }
 8   },
 9   --- other globals...
10}

Per-file and per-path overrides

The environment in which luacheck loads the config contains a special global files. When checking a file <path>, luacheck will override options from the main config with entries from files[<glob>] if <glob> matches <path>, applying entries for more general globs first. For example, the following config re-enables detection of unused arguments only for files in src/dir, but not for files ending with _special.lua, and allows using Busted globals within spec/:

1std = "min"
2ignore = {"212"}
3files["src/dir"] = {enable = {"212"}}
4files["src/dir/**/*_special.lua"] = {ignore = {"212"}}
5files["spec"] = {std = "+busted"}

Note that files table supports autovivification, so that

files["src/dir"].enable = {"212"}

and

files["src/dir"] = {enable = {"212"}}

are equivalent.