Skip to main content

​
Overview

EmmyLua Analyzer provides a powerful language server for Lua development in VS Code through the official EmmyLua extension. Get intelligent code completion, type checking, and advanced analysis features.
Prerequisites:
  • Visual Studio Code version 1.60 or higher
  • EmmyLua Analyzer installed (cargo install emmylua_ls)

​
Installation

1

Install EmmyLua Extension

Install the EmmyLua Extension from the VS Code Marketplace:
code --install-extension tangzx.emmylua
2

Configure Language Server Path

If you installed emmylua_ls via cargo, the extension should automatically detect it. Otherwise, specify the path in your settings:
settings.json
{
  "emmylua.languageServer.path": "/path/to/emmylua_ls"
}
To find the installation path:
which emmylua_ls
3

Create Configuration File

Create a .emmyrc.json file in your project root for project-specific settings:
.emmyrc.json
{
  "$schema": "https://raw.githubusercontent.com/EmmyLuaLs/emmylua-analyzer-rust/refs/heads/main/crates/emmylua_code_analysis/resources/schema.json",
  "runtime": {
    "version": "LuaLatest"
  },
  "diagnostics": {
    "enable": true
  },
  "completion": {
    "enable": true,
    "callSnippet": true
  }
}

​
Configuration

​
Workspace Settings

Configure EmmyLua in your workspace settings (.vscode/settings.json): 
{
  "emmylua.completion.enable": true,
  "emmylua.diagnostics.enable": true,
  "emmylua.hint.enable": true,
  "emmylua.hover.enable": true
}

​
Runtime Version

Specify the Lua version for your project: 
{
  "emmylua.runtime.version": "Lua5.4"
}
Available versions: Lua5.1, Lua5.2, Lua5.3, Lua5.4, LuaJIT, LuaLatest

​
Diagnostics Configuration

Customize diagnostic behavior: 
{
  "emmylua.diagnostics.disable": ["undefined-global"],
  "emmylua.diagnostics.globals": ["vim", "awesome", "love"],
  "emmylua.diagnostics.severity": {
    "unused": "hint",
    "undefined-global": "warning"
  }
}

​
Code Formatting

Enable and configure the built-in formatter: 
{
  "[lua]": {
    "editor.defaultFormatter": "tangzx.emmylua",
    "editor.formatOnSave": true
  },
  "emmylua.reformat.enable": true
}

​
Keyboard Shortcuts

​
Default Keybindings

ActionWindows/LinuxmacOS
Go to DefinitionF12F12
Peek DefinitionAlt+F12Option+F12
Find ReferencesShift+F12Shift+F12
Rename SymbolF2F2
Format DocumentShift+Alt+FShift+Option+F
Show HoverCtrl+K Ctrl+ICmd+K Cmd+I
Trigger CompletionCtrl+SpaceCmd+Space

​
Custom Keybindings

Add custom keybindings in keybindings.json: 
[
  {
    "key": "ctrl+shift+r",
    "command": "emmylua.restart",
    "when": "editorLangId == lua"
  },
  {
    "key": "ctrl+shift+d",
    "command": "emmylua.showReferences",
    "when": "editorLangId == lua"
  }
]

​
Features

​
Intelligent Code Completion

  • Context-aware completions with type information
  • Auto-import suggestions
  • Function signature hints
  • Snippet support

​
Type Checking

  • Real-time type inference
  • EmmyLua and Luacats annotation support
  • Type mismatch detection
  • Nil safety checks
  • Go to definition across files
  • Find all references
  • Workspace symbol search
  • Document outline

​
Code Actions

  • Quick fixes for common issues
  • Add missing annotations
  • Disable diagnostics for specific lines
  • Extract to function/variable

​
Troubleshooting

Solution:
  1. Check if emmylua_ls is installed: 
    emmylua_ls --version
  2. Verify the language server path in settings: 
    {
  "emmylua.languageServer.path": "/path/to/emmylua_ls"
}
  3. Check the Output panel (View > Output) and select “EmmyLua” from the dropdown
  4. Restart the language server:
    • Press Ctrl+Shift+P (Cmd+Shift+P on macOS)
    • Run command: EmmyLua: Restart Language Server
Solution:
  1. Ensure completion is enabled: 
    {
  "emmylua.completion.enable": true
}
  2. Check if the file is recognized as Lua (bottom-right corner of VS Code)
  3. Verify workspace indexing is complete (check status bar)
  4. Try reindexing the workspace:
    • Command: EmmyLua: Reindex Workspace
Solution:
  1. Add global variables to the whitelist: 
    {
  "emmylua.diagnostics.globals": ["myGlobal"]
}
  2. Disable specific diagnostics: 
    {
  "emmylua.diagnostics.disable": ["undefined-global"]
}
  3. Use inline diagnostic control: 
    ---@diagnostic disable-next-line: undefined-global
print(myGlobal)
  4. Configure library paths: 
    {
  "emmylua.workspace.library": ["./libs"]
}
Solution:
  1. Ignore unnecessary directories: 
    {
  "emmylua.workspace.ignoreDir": [
    "node_modules",
    "build",
    "dist"
  ]
}
  2. Use glob patterns to exclude files: 
    {
  "emmylua.workspace.ignoreGlobs": [
    "**/*.log",
    "**/test_*"
  ]
}
  3. Adjust preload file size limit: 
    {
  "emmylua.workspace.preloadFileSize": 1000
}
  4. Disable features you don’t need: 
    {
  "emmylua.codeLens.enable": false,
  "emmylua.semanticTokens.enable": false
}
Solution:
  1. Set EmmyLua as the default formatter: 
    {
  "[lua]": {
    "editor.defaultFormatter": "tangzx.emmylua"
  }
}
  2. Enable formatting: 
    {
  "emmylua.reformat.enable": true
}
  3. Check for conflicting formatters (disable other Lua formatters)
  4. Try formatting manually: Shift+Alt+F (Windows/Linux) or Shift+Option+F (macOS)

​
Multi-root Workspaces

For multi-root workspaces, configure each workspace folder separately:
workspace.code-workspace
{
  "folders": [
    {
      "path": "project1",
      "settings": {
        "emmylua.runtime.version": "Lua5.1"
      }
    },
    {
      "path": "project2",
      "settings": {
        "emmylua.runtime.version": "LuaJIT"
      }
    }
  ]
}

​
Next Steps

Configuration

Learn about all available configuration options

Annotations

Add type annotations to your code

Features

Explore all language server features

Troubleshooting

Optimize performance for large projects

Build docs developers (and LLMs) love

Get started for freeTalk to us