Skip to main content

​
Overview

emmylua_ls is a high-performance Language Server Protocol implementation for Lua, providing intelligent code completion, diagnostics, and advanced language features to editors and IDEs.

​
Installation

cargo install emmylua_ls

​
Basic Usage

emmylua_ls

​
Command-Line Options

​
Communication Options

​
--communication
string
default:"stdio"
Communication method for the language server.Available values:
  • stdio - Standard input/output (default, recommended for editor integration)
  • tcp - TCP socket connection (useful for remote debugging)
# Use stdio mode (default)
emmylua_ls --communication stdio

# Use TCP mode for remote debugging
emmylua_ls --communication tcp
​
--ip
string
default:"127.0.0.1"
IP address to listen on. Only valid when using TCP communication mode.
# Listen on localhost (default)
emmylua_ls -c tcp --ip 127.0.0.1

# Listen on all interfaces
emmylua_ls -c tcp --ip 0.0.0.0
​
--port
number
default:"5007"
Port number to listen on. Only valid when using TCP communication mode.
# Use default port
emmylua_ls -c tcp --port 5007

# Use custom port
emmylua_ls -c tcp --port 8080

​
Logging Options

​
--log-level
string
default:"info"
Set the logging verbosity level.Available values:
  • error - Only log errors
  • warn - Log warnings and errors
  • info - Log informational messages (default)
  • debug - Verbose debug logging
# Info level (default)
emmylua_ls --log-level info

# Debug mode for troubleshooting
emmylua_ls --log-level debug

# Quiet mode (errors only)
emmylua_ls --log-level error
​
--log-path
string
default:"none"
Path to the log file directory. Use none to disable file logging.
# Disable file logging (default)
emmylua_ls --log-path none

# Log to specific directory
emmylua_ls --log-path ./logs

# Log to absolute path
emmylua_ls --log-path /var/log/emmylua

​
Advanced Options

​
--resources-path
string
default:""
Path to the resources and logs directory. Use none to prevent assets from being written to the file system.
# Use default location
emmylua_ls --resources-path ""

# Custom resources directory
emmylua_ls --resources-path ./emmylua-resources

# Disable file system output
emmylua_ls --resources-path none
​
--load-stdlib
boolean
default:"true"
Whether to load the Lua standard library definitions.
# Load standard library (default)
emmylua_ls --load-stdlib true

# Disable standard library
emmylua_ls --load-stdlib false
​
--editor
string
Force a specific editor mode for client-specific optimizations.Available values:
  • vscode - Visual Studio Code
  • intellij - IntelliJ IDEA / JetBrains IDEs
  • neovim - Neovim
# Auto-detect editor (default)
emmylua_ls

# Force VSCode mode
emmylua_ls --editor vscode

# Force Neovim mode
emmylua_ls --editor neovim

​
Editor Integration

​
VS Code

Install the EmmyLua extension from the marketplace. The extension automatically starts the language server. Custom configuration in settings.json: 
{
  "emmylua.server.path": "/path/to/emmylua_ls",
  "emmylua.server.args": [
    "--log-level", "debug",
    "--log-path", "./logs"
  ]
}

​
Neovim

local lspconfig = require('lspconfig')

lspconfig.emmylua_ls.setup({
  cmd = { 'emmylua_ls' },
  settings = {
    emmylua = {
      -- Your configuration here
    }
  }
})

​
IntelliJ IDEA

Install the EmmyLua2 plugin from the JetBrains Marketplace.

​
Other Editors

Any editor supporting LSP can use emmylua_ls. Configure your LSP client to execute: 
emmylua_ls --communication stdio

​
Communication Modes

​
STDIO Mode (Default)

Best for: Direct editor integration The language server communicates via standard input/output streams. This is the default and recommended mode for most use cases. 
emmylua_ls --communication stdio
Characteristics:
  • Zero network configuration
  • Process-isolated
  • Automatic lifecycle management by editor
  • Best performance for local development

​
TCP Mode

Best for: Remote development, debugging, and testing The language server listens on a TCP socket, allowing remote connections. 
emmylua_ls --communication tcp --ip 127.0.0.1 --port 5007
Characteristics:
  • Network-based communication
  • Can connect from remote machines
  • Useful for debugging LSP protocol
  • Requires manual process management
# Start server on default port
emmylua_ls -c tcp

# Output:
# EmmyLua Language Server
# Listening on 127.0.0.1:5007
# Waiting for client connections...

# Connect from your editor's LSP client
# Configure client to connect to tcp://127.0.0.1:5007

​
Logging Configuration

​
Log Levels

# Only critical errors
emmylua_ls --log-level error

​
Log File Management

# Log to file
emmylua_ls --log-path ./logs

# Log files are created with timestamps:
# ./logs/emmylua-ls-2026-03-05-14-30-00.log

# Disable file logging (output to stderr only)
emmylua_ls --log-path none

​
Troubleshooting

​
Enable Debug Logging

For investigating issues, enable debug logging: 
emmylua_ls --log-level debug --log-path ./troubleshooting-logs

​
Check Server Status

When using TCP mode, verify the server is listening: 
# Start in TCP mode
emmylua_ls -c tcp --port 5007 &

# Verify connection
netstat -an | grep 5007
# Or on macOS/BSD:
lsof -i :5007

​
Common Issues

Check permissions:
# Ensure executable
chmod +x emmylua_ls

# Verify it runs
emmylua_ls --version
Check port availability (TCP mode):
# Verify port is not in use
netstat -an | grep 5007

# Try different port
emmylua_ls -c tcp --port 5008
For large projects:
  • Ensure .emmyrc.json excludes build directories
  • Add patterns to ignore in workspace configuration
  • Consider using --load-stdlib false if not needed
Verify standard library is loaded:
emmylua_ls --load-stdlib true
Check workspace configuration:
  • Ensure .emmyrc.json or .luarc.json exists
  • Verify file patterns include your source files

​
Advanced Configuration

​
Multiple Workspace Folders

The language server automatically handles multi-root workspaces through LSP protocol messages. Configure workspace folders in your editor.

​
Custom Standard Library

To use a custom standard library definition:
  1. Create .emmyrc.json in your workspace
  2. Disable built-in stdlib: emmylua_ls --load-stdlib false
  3. Add your custom definitions in the workspace

​
Performance Tuning

# Disable file logging and resource output
emmylua_ls \
  --log-path none \
  --resources-path none \
  --log-level error

​
Exit Codes

  • 0 - Clean exit
  • 1 - Configuration error
  • 2 - Connection error (TCP mode)
  • Other non-zero - Unexpected error (check logs)

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us