Configuration

See also

See our guide on how to configure EmmyLua.

Loading order

EmmyLua will search for configs in the following order. Values from configs higher in the list override values from configs lower in the list:

  1. local .emmyrc.json: a JSON file located in your project’s root,

  2. local .luarc.json: a JSON file located in your project’s root,

  3. a JSON file specified by environment variable $EMMYLUALS_CONFIG,

  4. global <config-dir>/emmylua_ls/.emmyrc.json,

  5. global <config-dir>/emmylua_ls/.luarc.json,

  6. global <home-dir>/.emmyrc.json,

  7. global <home-dir>/.luarc.json.

Depending on your platform, <config-dir> will be different:

Platform

Value

Example

Linux

$XDG_CONFIG_HOME or $HOME/.config

/home/alice/.config

macOS

$HOME/Library/Application Support

/Users/Alice/Library/Application Support

Windows

{FOLDERID_RoamingAppData}

C:\Users\Alice\AppData\Roaming

Full list of config values

codeAction

Configuration for code actions and quick fixes.

insertSpace: boolean = false

Add space after --- comments when inserting @diagnostic disable-next-line.

codeLens

Configuration for code lens features.

enable: boolean = true

Enable code lens.

completion

Configuration for code completion features.

autoRequire: boolean = true

When enabled, selecting a completion suggestion from another module will add the appropriate require statement.

autoRequireFunction: string = "require"

Name of the function that’s inserted when auto-requiring modules.

Default is "require", but can be customized to use any module loader function.

autoRequireNamingConvention = "keep"

The naming convention for auto-required filenames.

Controls how the imported module names are formatted in the require statement.

"keep"

Keep the original filename without any transformation.

Example: "my-module" remains "my-module".

"snake-case"

Convert the filename to snake_case.

Example: "MyModule" becomes "my_module".

"pascal-case"

Convert the filename to PascalCase.

Example: "my_module" becomes "MyModule".

"camel-case"

Convert the filename to camelCase.

Example: "my_module" becomes "myModule".

"keep-class"

When returning a class definition, use the class name; otherwise keep the original name.

This is useful for modules that export a single class with a name that might differ from the filename.

autoRequireSeparator: string = "."

Defines the character used to separate path segments in require statements.

Default is ".", but can be changed to other separators like "/".

baseFunctionIncludesName: boolean = true

Whether to include the name in the base function in postfix autocompletion.

Effect: function () end -> function name() end.

callSnippet: boolean = false

Whether to use call snippets in completions.

When enabled, function completions will insert a snippet with placeholders for function arguments, allowing for quick tabbing between parameters.

enable: boolean = true

Enable autocompletion.

postfix: string = "@"

Symbol that’s used to trigger postfix autocompletion.

diagnostics

Configuration for diagnostics and error detection.

diagnosticInterval: integer? = 500

Delay between opening/changing a file and scanning it for errors, in milliseconds.

disable: EmmyRc#DiagnosticCode[] = []

A list of suppressed diagnostics.

enable: boolean = true

A flag indicating whether diagnostics are enabled at all.

enables: EmmyRc#DiagnosticCode[] = []

A list of diagnostic codes that are enabled, in addition to default ones.

globals: string[] = []

A list of global variables.

Variables from this list are always treated as defined globals.

globalsRegex: string[] = []

A list of regular expressions for global variables.

Variables that match these regular expressions are always treated as defined globals.

severity: {string: "error" | "warning" | "information" | "hint"} = {}

A map of diagnostic codes to their severity settings.

"error"

Represents an error diagnostic severity.

"warning"

Represents a warning diagnostic severity.

"information"

Represents an information diagnostic severity.

"hint"

Represents a hint diagnostic severity.

doc

Configuration for documentation parsing.

knownTags: string[] = []

List of known documentation tags.

privateName: string[] = []

List of glob patterns that enable treating specific field names as private.

For example, m_* would make fields Type.m_id and Type.m_type private.

rstDefaultRole: string? = null

When syntax is Myst or Rst, specifies default role used with RST processor.

rstPrimaryDomain: string? = null

When syntax is Myst or Rst, specifies primary domain used with RST processor.

syntax = "md"

Syntax for highlighting documentation.

"none"

Documentation is not highlighted.

"md"

Documentation is highlighted as plain MarkDown.

"myst"

Documentation is highlighted as MySt, a MarkDown plugin for Sphinx.

Enables Autocompletion and Go To Definition for sphinx cross-references.

"rst"

Documentation is highlighted as ReStructured Text.

Enables Autocompletion and Go To Definition for sphinx cross-references.

documentColor

Configuration for document color features.

enable: boolean = true

Enable parsing strings for color tags and showing a color picker next to them.

format

Configuration for code formatting.

externalTool

Configuration for external formatting tool.

args: string[] = []

List of arguments to pass to the external tool.

Each argument can contain the following patterns:

  • ${file} expands to the file path that needs formatting;

  • ${indent_size} expands to numeric value for indentation size;

  • ${use_tabs?<on_yes>:<on_no>} expands to <on_yes> placeholder or <on_no> placeholder depending on whether tabs are used for indentation.

    For example, ${use_tabs?--tabs} will expand to --tabs if tabs are required, or an empty string if tabs are not required.

  • ${insert_final_newline?<on_yes>:<on_no>} expands to <on_yes> placeholder or <on_no> placeholder depending on whether the tool should insert final newline.

  • ${non_standard_symbol?<on_yes>:<on_no>} expands to <on_yes> placeholder or <on_no> placeholder depending on whether non-standard symbols are enabled.

program: string = ""

The command to run the external tool.

timeout: integer = 5000

Command timeout, in milliseconds.

useDiff: boolean = false

Whether to use the diff algorithm for formatting.

hint

Configuration for inlay hints in the editor.

enable: boolean = true

Enable inlay hints.

enumParamHint: boolean = false

Show name of enumerator when passing a literal value to a function that expects an enum.

Example:

--- @enum Level
local Foo = {
   Info = 1,
   Error = 2,
}

--- @param l Level
function print_level(l) end

print_level(1 --[[ Hint: Level.Info ]])
indexHint: boolean = true

Show named array indexes.

Example:

local array = {
   [1] = 1, -- [name]
}

print(array[1] --[[ Hint: name ]])
localHint: boolean = true

Show types of local variables.

metaCallHint: boolean = true

Show hint when calling an object results in a call to its meta table’s __call function.

overrideHint: boolean = true

Show methods that override functions from base class.

paramHint: boolean = true

Show parameter names in function calls and parameter types in function definitions.

hover

Configuration for hover information.

enable: boolean = true

Enable showing documentation on hover.

inlineValues

Configuration for inline value display.

enable: boolean = true

Show inline values during debug.

references

Configuration for reference lookup features.

enable: boolean = true

Enable searching for symbol usages.

fuzzySearch: boolean = true

Use fuzzy search when searching for symbol usages and normal search didn’t find anything.

shortStringSearch: boolean = false

Also search for usages in strings.

resource

Configuration for resource file management.

paths: string[] = []

List of resource directories used in a project. Files from these directories will be added to autocompletion when completing file paths.

This list can contain anything, like directories with game assets, template files, and so on. No special interpretation beyond autocompletion is given to these paths.

runtime

Configuration for Lua runtime.

classDefaultCall

Controls resolution of class constructors.

forceNonColon: boolean = false

Remove the self parameter from list of constructor parameters when inferring constructor signature using functionName.

forceReturnSelf: boolean = false

Always use self as constructor’s return type when inferring constructor signature using functionName.

functionName: string = ""

Name of the method that’s used to resolve class default __call operator.

For example, if functionName is "__init", then EmmyLua will use parameters and return types of __init method as parameters and return types of class’ __call operator:

--- @class Example
--- @field __init fun(): Example

-- Unless `Example` provides its own `@overload`,
-- any call to `Example()` is treated as a call to `Example:__init()`:
local example = Example()
--    ^^^^^^^ type of `example` is inferred as `Example`.
extensions: string[] = []

Extensions of Lua files that need analysis.

Example: [".lua", ".lua.txt"].

frameworkVersions: string[] = []
nonstandardSymbol: ("//" | "/**/" | "`" | "+=" | "-=" | "*=" | "/=" | "%=" | "^=" | "//=" | "|=" | "&=" | "<<=" | ">>=" | "||" | "&&" | "!" | "!=" | "continue")[] = []

List of enabled non-standard symbols.

"//"
"/**/"
"`"
"+="
"-="
"*="
"/="
"%="
"^="
"//="
"|="
"&="
"<<="
">>="
"||"
"&&"
"!"
"!="
"continue"
requireLikeFunction: string[] = []

Functions that are treated like require.

requirePattern: string[] = []

Require pattern in the format of Lua’s path.

Example: ["?.lua", "?/init.lua"].

version = "LuaLatest"

Lua version.

"Lua5.1"

Lua 5.1

"LuaJIT"

LuaJIT

"Lua5.2"

Lua 5.2

"Lua5.3"

Lua 5.3

"Lua5.4"

Lua 5.4

"Lua5.5"

Lua 5.5

"LuaLatest"

Lua Latest, currently set to Lua5.4.

semanticTokens

Configuration for semantic token highlighting.

enable: boolean = true

Enable semantic tokens.

renderDocumentationMarkup: boolean = true

Render Markdown/RST in documentation. Set doc.syntax for this option to have effect.

signature

Configuration for function signature help.

detailSignatureHelper: boolean = true

Whether to enable signature help.

strict

Configuration for strict type checks.

arrayIndex: boolean = true

Whether to enable strict mode when inferring type of array indexing operation.

docBaseConstMatchBaseType: boolean = true

Base constant types defined in doc can match base types, allowing int to match ---@alias id 1|2|3, same for string.

metaOverrideFileDefine: boolean = true

Definitions from @meta files always overrides definitions from normal files.

requirePath: boolean = false

Whether to enable strict mode for resolving require paths.

typeCall: boolean = false
workspace

Configuration for workspace management.

enableReindex: boolean = false

Enable full project reindex after changing a file.

encoding: string = "utf-8"

File encoding.

ignoreDir: string[] = []

List of ignored directories.

ignoreGlobs: string[] = []

List of globs for ignored files.

library: string[] = []

List of library roots.

Example: "/usr/local/share/lua/5.1".

moduleMap: {'pattern': string, 'replace': string}[] = []

Module map. Allows customizing conversion from file paths to module names and require paths.

This is a list of objects, each containing a regular expression and a replace string. When generating module name for a file, EmmyLua will reverse-match file path with require patterns, generate an appropriate module name, then run it through these replace patterns to get the final module name.

Example:

{
    "workspace": {
        "moduleMap": [
            {
                "pattern": "^_core\\.public\\.(.*)$",
                "replace": "@core.$1"
            }
        ]
    }
}
required pattern: string

Regular expression that will be matched against the generated module name. See regex crate for details about syntax.

required replace: string

Replace string. Use $name to substitute capturing groups from regex.

preloadFileSize: integer = 0
reindexDuration: integer = 5000

Delay between changing a file and full project reindex, in milliseconds.

workspaceRoots: string[] = []

List of workspace roots.

Example: ["src", "test"].