Settings

Explore the settings for customizing how the language server works.

Important

All of these settings should be prefixed with Lua. (e.g. Lua.completion.enable) when editing a configuration file - except when using a .luarc.json file. When using a .luarc.json file, the prefix is not needed and the settings can be entered as they appear on this page.

addonManager

Settings that affect the addon manager.

addonManager.enable

Type: boolean
Default: true

Set the on/off state of the addon manager. Disabling the addon manager prevents it from registering its command.

completion

Settings that adjust how autocompletions are provided while typing.

completion.autoRequire

Type: boolean
Default: true

When the input looks like a file name, automatically require the file.

completion.callSnippet

Type: string
Default: "Disable"
Options:

"Disable" - Only show function name
"Both" - Show function name and snippet
"Replace" - Only show the call snippet

Whether to show call snippets or not. When disabled, only the function name will be completed. When enabled, a "more complete" snippet will be offered.

JSON

{
  "completion.callSnippet": "Replace"
}

Note

The below example is using the "Both" option.

completion.displayContext

Type: integer
Default: 0 (disabled)

When a completion is being suggested, this setting will set the amount of lines around the definition to preview to help you better understand its usage.

Setting to 0 will disable this feature.

completion displayContext

completion.enable

Type: boolean
Default: true

Enable/disable completion. Completion works like any autocompletion you already know of. It helps you type less and get more done.

completion.keywordSnippet

Type: string
Default: "Replace"
Options:

"Disable" - Only completes the keyword
"Both" - Offers a completion for the keyword and snippet
"Replace" - Only shows a snippet

Whether to show a snippet for key words like if, while, etc. When disabled, only the keyword will be completed. When enabled, a "more complete" snippet will be offered.

Note

The below example is using the "Both" option.

completion.postfix

Type: string
Default: @

The character to use for triggering a "postfix suggestion". A postfix allows you to write some code and then trigger a snippet after (post) to "fix" the code you have written. This can save some time as instead of typing table.insert(myTable, ), you can just type myTable@.

completion.requireSeparator

Type: string
Default: .

The separator to use when require-ing a file.

completion.showParams

Type: boolean
Default: true

Display a function's parameters in the list of completions. When a function has multiple definitions, they will be displayed separately.

completion.showWord

Type: string
Default: "Fallback"
Options:

"Enable" - Always show contextual words in completion suggestions
"Fallback" - Only show contextual words when smart suggestions based on semantics cannot be provided
"Disable" - Never show contextual words

Show "contextual words" that have to do with Lua but are not suggested based on their usefulness in the current semantic context.

completion.workspaceWord

Type: boolean
Default: true

Whether words from other files in the workspace should be suggested as "contextual words". This can be useful for completing similar strings. completion.showWord must not be disabled for this to have an effect.

diagnostics

Settings to adjust the diagnostics.

diagnostics.disable

Type: Array<diagnostic_name>
Default: []

Disable certain diagnostics globally.

JSON

{
  "diagnostics.disable": ["lowercase-global"]
}

diagnostics.disableScheme

Type: Array<string>
Default: ["git"]

Disable diagnosis of Lua files that have the set schemes.

diagnostics.enable

Type: boolean
Default: true

Whether all diagnostics should be enabled or not.

diagnostics.globals

Type: Array<string>
Default: []

An array of variable names that will be declared as global.

JSON

{
  "diagnostics.globals": ["myGlobal"]
}

diagnostics.groupFileStatus

Type: Object<diagnostic_group_name, file_state>

file_state options:

"Any" - Any loaded file (workspace, library, etc.) will use this diagnostic group
"Opened" - Only opened files will use this diagnostic group
"None" - This diagnostic group will be disabled
"Fallback" - The diagnostics in this group are controlled individually by diagnostics.neededFileStatus

Default Value

JSON

{
  /*
   * ambiguity-1
   * count-down-loop
   * different-requires
   * newfield-call
   * newline-call
   */
  "ambiguity": "Fallback",
  /*
   * await-in-sync
   * not-yieldable
   */
  "await": "Fallback",
  /*
   * codestyle-check
   * spell-check
   */
  "codestyle": "Fallback",
  /*
   * duplicate-index
   * duplicate-set-field
   */
  "duplicate": "Fallback",
  /*
   * global-in-nil-env
   * lowercase-global
   * undefined-env-child
   * undefined-global
   */
  "global": "Fallback",
  /*
   * cast-type-mismatch
   * circle-doc-class
   * doc-field-no-class
   * duplicate-doc-alias
   * duplicate-doc-field
   * duplicate-doc-param
   * undefined-doc-class
   * undefined-doc-name
   * undefined-doc-param
   * unknown-cast-variable
   * unknown-diag-code
   * unknown-operator
   */
  "luadoc": "Fallback",
  /*
   * redefined-local
   */
  "redefined": "Fallback",
  /*
   * close-non-object
   * deprecated
   * discard-returns
   */
  "strict": "Fallback",
  /*
   * no-unknown
   */
  "strong": "Fallback",
  /*
   * assign-type-mismatch
   * cast-local-type
   * cast-type-mismatch
   * need-check-nil
   * param-type-mismatch
   * return-type-mismatch
   * undefined-field
   */
  "type-check": "Fallback",
  /*
   * missing-parameter
   * missing-return
   * missing-return-value
   * redundant-parameter
   * redundant-return-value
   * redundant-value
   * unbalanced-assignments
   */
  "unbalanced": "Fallback",
  /*
   * code-after-break
   * empty-block
   * redundant-return
   * trailing-space
   * unreachable-code
   * unused-function
   * unused-label
   * unused-local
   * unused-vararg
   */
  "unused": "Fallback"
}

Set the file status required for each diagnostic group. This setting is an Object of key-value pairs where the key is the name of the diagnostic group and the value is the state that a file must be in in order for the diagnostic group to apply.

diagnostics.groupSeverity

Type: Object<diagnostic_group_name, severity>

severity options:

"Error" - An error will be raised
"Warning" - A warning will be raised
"Information" - An information or note will be raised
"Hint" - The affected code will be "hinted" at
"Fallback" - The diagnostics in this group will be controlled individually by diagnostics.severity

Default Value

JSON

{
  /*
   * ambiguity-1
   * count-down-loop
   * different-requires
   * newfield-call
   * newline-call
   */
  "ambiguity": "Fallback",
  /*
   * await-in-sync
   * not-yieldable
   */
  "await": "Fallback",
  /*
   * codestyle-check
   * spell-check
   */
  "codestyle": "Fallback",
  /*
   * duplicate-index
   * duplicate-set-field
   */
  "duplicate": "Fallback",
  /*
   * global-in-nil-env
   * lowercase-global
   * undefined-env-child
   * undefined-global
   */
  "global": "Fallback",
  /*
   * cast-type-mismatch
   * circle-doc-class
   * doc-field-no-class
   * duplicate-doc-alias
   * duplicate-doc-field
   * duplicate-doc-param
   * undefined-doc-class
   * undefined-doc-name
   * undefined-doc-param
   * unknown-cast-variable
   * unknown-diag-code
   * unknown-operator
   */
  "luadoc": "Fallback",
  /*
   * redefined-local
   */
  "redefined": "Fallback",
  /*
   * close-non-object
   * deprecated
   * discard-returns
   */
  "strict": "Fallback",
  /*
   * no-unknown
   */
  "strong": "Fallback",
  /*
   * assign-type-mismatch
   * cast-local-type
   * cast-type-mismatch
   * need-check-nil
   * param-type-mismatch
   * return-type-mismatch
   * undefined-field
   */
  "type-check": "Fallback",
  /*
   * missing-parameter
   * missing-return
   * missing-return-value
   * redundant-parameter
   * redundant-return-value
   * redundant-value
   * unbalanced-assignments
   */
  "unbalanced": "Fallback",
  /*
   * code-after-break
   * empty-block
   * redundant-return
   * trailing-space
   * unreachable-code
   * unused-function
   * unused-label
   * unused-local
   * unused-vararg
   */
  "unused": "Fallback"
}

diagnostics.ignoredFiles

Type: string
Default: "Opened"
Options:

"Enable" - Always diagnose ignored files... kind of defeats the purpose of ignoring them.
"Opened" - Only diagnose ignored files when they are open
"Disable" - Ignored files are fully ignored

Set how files that have been ignored should be diagnosed.

diagnostics.libraryFiles

Type: string
Default: "Opened"
Options:

"Enable" - Always diagnose library files
"Opened" - Only diagnose library files when they are open
"Disable" - Never diagnose library files

Set how files loaded with workspace.library are diagnosed.

diagnostics.neededFileStatus

Type: Object<diagnostic_name, file_state>

file_state options:

"Any" - Any loaded file (workspace, library, etc.) will use this diagnostic group
"Opened" - Only opened files will use this diagnostic group
"None" - This diagnostic group will be disabled
"Any!" - Like "Any" but overrides diagnostics.groupFileStatus
"Opened!" - Like "Opened" but overrides diagnostics.groupFileStatus
"None!" - Like "None" but overrides diagnostics.groupFileStatus

Default Value

JSON

{
  "ambiguity-1": "Any",
  "assign-type-mismatch": "Opened",
  "await-in-sync": "None",
  "cast-local-type": "Opened",
  "cast-type-mismatch": "Any",
  "circle-doc-class": "Any",
  "close-non-object": "Any",
  "code-after-break": "Opened",
  "codestyle-check": "None",
  "count-down-loop": "Any",
  "deprecated": "Any",
  "different-requires": "Any",
  "discard-returns": "Any",
  "doc-field-no-class": "Any",
  "duplicate-doc-alias": "Any",
  "duplicate-doc-field": "Any",
  "duplicate-doc-param": "Any",
  "duplicate-index": "Any",
  "duplicate-set-field": "Any",
  "empty-block": "Opened",
  "global-in-nil-env": "Any",
  "lowercase-global": "Any",
  "missing-parameter": "Any",
  "missing-return": "Any",
  "missing-return-value": "Any",
  "need-check-nil": "Opened",
  "newfield-call": "Any",
  "newline-call": "Any",
  "no-unknown": "None",
  "not-yieldable": "None",
  "param-type-mismatch": "Opened",
  "redefined-local": "Opened",
  "redundant-parameter": "Any",
  "redundant-return": "Opened",
  "redundant-return-value": "Any",
  "redundant-value": "Any",
  "return-type-mismatch": "Opened",
  "spell-check": "None",
  "trailing-space": "Opened",
  "unbalanced-assignments": "Any",
  "undefined-doc-class": "Any",
  "undefined-doc-name": "Any",
  "undefined-doc-param": "Any",
  "undefined-env-child": "Any",
  "undefined-field": "Opened",
  "undefined-global": "Any",
  "unknown-cast-variable": "Any",
  "unknown-diag-code": "Any",
  "unknown-operator": "Any",
  "unreachable-code": "Opened",
  "unused-function": "Opened",
  "unused-label": "Opened",
  "unused-local": "Opened",
  "unused-vararg": "Opened"
}

diagnostics.severity

Type: Object<diagnostic_name, severity>

severity options:

"Error" - An error will be raised
"Warning" - A warning will be raised
"Information" - An information or note will be raised
"Hint" - The affected code will be "hinted" at
"Error!" - Like "Error" but overrides diagnostics.groupSeverity
"Warning!" -Like "Warning" but overrides diagnostics.groupSeverity
"Information!" - Like "Information" but overrides diagnostics.groupSeverity
"Hint!" - Like "Hint" but overrides diagnostics.groupSeverity

Default Value

JSON

{
  "ambiguity-1": "Warning",
  "assign-type-mismatch": "Warning",
  "await-in-sync": "Warning",
  "cast-local-type": "Warning",
  "cast-type-mismatch": "Warning",
  "circle-doc-class": "Warning",
  "close-non-object": "Warning",
  "code-after-break": "Hint",
  "codestyle-check": "Warning",
  "count-down-loop": "Warning",
  "deprecated": "Warning",
  "different-requires": "Warning",
  "discard-returns": "Warning",
  "doc-field-no-class": "Warning",
  "duplicate-doc-alias": "Warning",
  "duplicate-doc-field": "Warning",
  "duplicate-doc-param": "Warning",
  "duplicate-index": "Warning",
  "duplicate-set-field": "Warning",
  "empty-block": "Hint",
  "global-in-nil-env": "Warning",
  "lowercase-global": "Information",
  "missing-parameter": "Warning",
  "missing-return": "Warning",
  "missing-return-value": "Warning",
  "need-check-nil": "Warning",
  "newfield-call": "Warning",
  "newline-call": "Warning",
  "no-unknown": "Warning",
  "not-yieldable": "Warning",
  "param-type-mismatch": "Warning",
  "redefined-local": "Hint",
  "redundant-parameter": "Warning",
  "redundant-return": "Hint",
  "redundant-return-value": "Warning",
  "redundant-value": "Warning",
  "return-type-mismatch": "Warning",
  "spell-check": "Information",
  "trailing-space": "Hint",
  "unbalanced-assignments": "Warning",
  "undefined-doc-class": "Warning",
  "undefined-doc-name": "Warning",
  "undefined-doc-param": "Warning",
  "undefined-env-child": "Information",
  "undefined-field": "Warning",
  "undefined-global": "Warning",
  "unknown-cast-variable": "Warning",
  "unknown-diag-code": "Warning",
  "unknown-operator": "Warning",
  "unreachable-code": "Hint",
  "unused-function": "Hint",
  "unused-label": "Hint",
  "unused-local": "Hint",
  "unused-vararg": "Hint"
}

diagnostics.unusedLocalExclude

Type: Array<string>
Default: []

Define variable names that will not be reported as an unused local by unused-local.

diagnostics.workspaceDelay

Type: integer
Default: 3000

Define the delay between diagnoses of the workspace in milliseconds. Every time a file is edited, created, deleted, etc. the workspace will be re-diagnosed in the background after this delay. Setting to a negative number will disable automatic workspace diagnostics.

diagnostics.workspaceEvent

Type: string
Default: "OnSave"
Options:

"OnChange"
"OnSave"
"None"

Set when the workspace diagnostics should be analyzed. It can be performed after each change, after a save, or never automatically triggered.

diagnostics.workspaceRate

Type: integer
Default: 100

Define the rate at which the workspace will be diagnosed as a percentage. 100 is 100% speed so the workspace will be diagnosed as fast as possible. The rate can be lowered to reduce CPU usage, but the diagnosis speed will also become slower. The currently opened file will always be diagnosed at 100% speed, regardless of this setting.

doc

Settings for configuring documentation comments.

doc.packageName

Type: Array<string>
Default: []

The pattern used for matching table field names as a package-private field. Fields that match any of the patterns provided will be package-private.

doc.privateName

Type: Array<string>
Default: []

The pattern used for matching table field names as a private field. Fields that match any of the patterns provided will be private.

doc.protectedName

Type: Array<string>
Default: []

The pattern used for matching field names as a protected field. Fields that match any of the patterns provided will be private to that class and its child classes.

format

Settings for configuring the built-in code formatter.

format.defaultConfig

Type: Object<string, string
Default: {}

The default configuration for the formatter. If there is a .editorconfig in the workspace, it will take priority. Read more on the formatter's GitHub page .

format.enable

Type: boolean
Default: true

Whether the built-in formatter should be enabled or not.

hint

Settings for configuring inline hints. See an example below.

hint.arrayIndex

Type: string
Default: "Auto"
Options:

"Enable" - Show hint in all tables
"Auto" - Only show hint when there is more than 3 items or the table is mixed (indexes and keys)
"Disable" - Disable array index hints

hint arrayIndex

hint.await

Type: boolean
Default: true

If a function has been defined as @async, display an await hint when it is being called.

hint.enable

Type: boolean
Default: false

Whether inline hints should be enabled or not.

hint.paramName

Type: string
Default: "All"
Options:

"All" - All parameters are hinted
"Literal" - Only literal type parameters are hinted
"Disable" - No parameter hints are shown

Whether parameter names should be hinted on function calls.

hint.paramType

Type: boolean
Default: true

Show a hint for parameter types at a function definition. Requires the parameters to be defined with @param.

hint.semicolon

Type: string
Default: "SameLine"
Options:

"All" - Show on every line
"SameLine" - Show between two statements on one line
"Disable" - Never hint a semicolon

Whether to show a hint to add a semicolon to the end of a statement.

hint.setType

Type: boolean
Default: false

Show a hint to display the type being applied at assignment operations.

hover

Setting for configuring hover tooltips. The hover tooltips can contain all kinds of useful information.

hover.enable

Type: boolean
Default: true

Whether to enable hover tooltips or not.

hover.enumsLimit

Type: integer
Default: 5

When a value has multiple possible types, hovering it will display them. This setting limits how many will be displayed in the tooltip before they are truncated.

hover.expandAlias

Type: boolean
Default: true

When hovering a value with an @alias for its type, should the alias be expanded into its values. When enabled, ---@alias myType boolean|number appears as boolean|number, otherwise it will appear as myType.

hover.previewFields

Type: integer
Default: 50

When a table is hovered, its fields will be displayed in the tooltip. This setting limits how many fields can be seen in the tooltip. Setting to 0 will disable this feature.

hover.viewNumber

Type: boolean
Default: true

Enable hovering a non-decimal value to see its numeric value.

hover.viewString

Type: boolean
Default: true

Enable hovering a string that contains an escape character to see its true string value. For example, hovering "\x48" will display "H".

hover.viewStringMax

Type: integer
Default: 1000

The maximum number of characters that can be previewed by hovering a string before it is truncated.

misc

Miscellaneous settings that do not belong to any of the other groups.

misc.parameters

Type: Array<string>
Default: []

Command line arguments to be passed along to the server executable when starting through Visual Studio Code.

misc.executablePath

Type: string
Default: ""

Manually specify the path for the Lua Language Server executable file.

runtime

Settings for configuring the runtime environment.

runtime.builtin

Type: Object< library , status>

status Options:

"default" - The library will be enabled if it is a part of the current runtime.version.
"enable" - Always enable this library
"disable" - Always disable this library

Default Value

JSON

{
  "basic": "default",
  "bit": "default",
  "bit32": "default",
  "builtin": "default",
  "coroutine": "default",
  "debug": "default",
  "ffi": "default",
  "io": "default",
  "jit": "default",
  "math": "default",
  "os": "default",
  "package": "default",
  "string": "default",
  "table": "default",
  "table.clear": "default",
  "table.new": "default",
  "utf8": "default"
}

Set whether each of the builtin Lua libraries is available in the current runtime environment.

runtime.fileEncoding

Type: string
Default: utf8
Options:

"utf8"
"ansi" (only available on Windows)
"utf16le"
"utf16be"

runtime.meta

Type: string
Default: "${version} ${language} ${encoding}"

Specify the template that should be used for naming the folders that contain the generated definitions for the various Lua versions, languages, and encodings.

runtime.nonstandardSymbol

Type: Array<string>
Default: []
Options:

"//"
"/**/"
"`"
"+="
"-="
"*="
"/="
"%="
"^="
"//="
"|="
"&="
"<<="
">>="
"||"
"&&"
"!"
"!="
"continue"

Add support for non-standard symbols. Make sure to double check that your runtime environment actually supports the symbols you are permitting as standard Lua does not.

runtime.path

Type: Array<string>
Default: ["?.lua", "?/init.lua"]

Defines the paths to use when using require. For example, setting to ?/start.lua will search for <workspace>/myFile/start.lua from the loaded files when doing require"myFile". If runtime.pathStrict is false, <workspace>/**/myFile/start.lua will also be searched. To load files that are not in the current workspace, they will first need to be loaded using workspace.library.

runtime.pathStrict

Type: boolean
Default: false

When enabled, runtime.path will only search the first level of directories.

runtime.plugin

Type: string
Default: ""

The path to the plugin to use. Blank by default to prevent unintentional execution of unknown code.

runtime.pluginArgs

Type: Array<string>
Default: []

Additional arguments that will be passed to the active plugin.

runtime.special

Type: Object<string, string>
Default: {}

"Special" variables can be set to be treated as other variables. For example, specifying "include" : "require" will result in include being treated like require.

runtime.unicodeName

Type: boolean
Default: false

Whether unicode characters should be allowed in variable names or not.

runtime.version

Type: string
Default: "Lua 5.4"
Options:

"Lua 5.1"
"Lua 5.2"
"Lua 5.3"
"Lua 5.4"
"LuaJIT"

The Lua runtime version to use in this environment.

semantic

The semantic group contains settings for semantic colouring in the editor.

semantic.annotation

Type: boolean
Default: true

Whether semantic colouring should be enabled for type annotations.

semantic.enable

Type: boolean
Default: true

Whether semantic colouring should be enabled. You may need to set editor.semanticHighlighting.enabled to true in order for this setting to take effect in Visual Studio Code.

semantic.keyword

Type: boolean
Default: false

Whether the server should provide semantic colouring of keywords, literals, and operators. You should only need to enable this setting if your editor is unable to highlight Lua's syntax.

semantic.variable

Type: boolean
Default: true

Whether the server should provide semantic colouring of variables, fields, and parameters.

signatureHelp

The signatureHelp group contains settings for helping understand signatures.

signatureHelp.enable

Type: boolean
Default: true

WIP

Description needed

spell

The spell group contains settings that help detect typos and misspellings.

spell.dict

Type: Array<string>
Default: []

A custom dictionary of words that you know are spelled correctly but are being reported as incorrect. Adding words to this dictionary will make them exempt from spell checking.

telemetry

The telemetry group contains settings for the opt-in telemetry.

Deprecated

Telemetry has been removed since v3.6.5, thank you for your positive feedback in the community!

telemetry.enable

Type: boolean | null
Default: null

The language server comes with opt-in telemetry to help improve the language server. It would be greatly appreciated if you enable this setting. Read the privacy policy before enabling.

type

The type group contains settings for type checking.

type.castNumberToInteger

Type: boolean
Default: false

Whether casting a number to an integer is allowed.

type.weakNilCheck

Type: boolean
Default: false

Whether it is permitted to assign a union type that contains nil to a variable that does not permit it. When false, the following will throw an error because number|nil cannot be assigned to number.

Lua

---@alias unionType number|nil

---@type number
local num

---@cast num unionType

type.weakUnionCheck

Type: boolean
Default: false

Whether it is permitted to assign a union type which only has one matching type to a variable. When false, the following will throw an error because string|boolean cannot be assigned to string.

Lua

---@alias unionType string|boolean

---@type string
local str = false

window

The window group contains settings that modify the window in VS Code.

window.progressBar

Type: boolean
Default: true

Show a progress bar in the bottom status bar that shows how the workspace loading is progressing.

window.statusBar

Type: boolean
Default: true

Show a Lua 😺 entry in the bottom status bar that can be clicked to manually perform a workspace diagnosis.

workspace

The workspace group contains settings for configuring how the workspace diagnosis works.

workspace.checkThirdParty

Type: string
Default: Ask
Options:

Ask (ask every time)
Apply (always apply automatically)
ApplyInMemory (always apply definition files, but don't apply setting)
Disable (Don't ask, don't apply)

Whether addons can be automatically detected and the user can be prompted to enable them. When prompted, you can "Apply and modify settings", "Apply but do not modify settings" (apply in RAM), or "Don't show again" (sets this setting to false). Addons can set up the environment to be as close as possible to your target runtime environment. To enable an addon manually, see the addons article.

workspace.ignoreDir

Type: Array<string>
Default: [".vscode"]

An array of paths that will be ignored and not included in the workspace diagnosis. Uses .gitignore grammar. Can be a file or directory.

workspace.ignoreSubmodules

Type: boolean
Default: true

Whether git submodules should be ignored and not included in the workspace diagnosis.

workspace.library

Type: Array<string>
Default: []

Used to add library implementation code and definition files to the workspace scope. An array of absolute/workspace-relative paths that will be added to the workspace diagnosis - meaning you will get completion and context from these files. Can be a file or directory. Files included here will have some features disabled such as renaming fields to prevent accidentally renaming your library files.

workspace.maxPreload

Type: integer
Default: 5000

The maximum amount of files that can be diagnosed. More files will require more RAM.

workspace.preloadFileSize

Type: integer
Default: 500

Files larger than this value (in KB) will be skipped when loading for workspace diagnosis.

workspace.useGitIgnore

Type: boolean
Default: true

Whether files that are in .gitignore should be ignored by the language server when performing workspace diagnosis.

workspace.userThirdParty

Type: Array<string>
Default: []

An array of paths to custom addons. This path should point to a directory where all of your addons are, not just to one. If the below is your file structure, this setting should be "myLuaLibraries" - of course this should be an absolute path though.

plaintext

📦 myLuaLibraries/
    ├── 📂 myAddon/
    │   ├── 📂 library/
    │   └── 📜 config.lua
    └── 📂 anotherAddon/
        ├── 📂 library/
        └── 📜 config.lua

Last Modified: 04:36:11 20 November, 2023 UTC