Managing LSP Servers with Mason

Mason is a package manager for Neovim that installs and manages LSP servers, DAP servers, linters, and formatters. It comes pre-configured with LazyVim and provides a simple UI for managing language tooling.

What Mason Does

Mason handles the complexity of LSP server installation:

Automated installation: Downloads and configures language servers
Isolated environments: Each server runs in its own environment (no conflicts)
Cross-platform: Works on macOS, Linux, and Windows
No manual dependency management: Handles Node.js, Python, Go, and other runtime requirements
Version management: Update or rollback servers easily
Integration with LazyVim: Installed servers are automatically detected and configured

The key benefit: You never need to manually install LSP servers with npm/pip/cargo/etc. Mason does it all.

Opening Mason

Inside Neovim:

vim
:Mason

Or use the LazyVim keybinding:

<Space> + c + m

This opens the Mason UI showing all available and installed packages.

The Mason interface uses simple keybindings:

Key	Action
`i`	Install package under cursor
`u`	Update package under cursor
`U`	Update all installed packages
`X`	Uninstall package under cursor
`/`	Filter/search packages
`g?`	Show help
`q`	Quit Mason UI
`j/k`	Navigate down/up
`Ctrl+f/b`	Scroll down/up

Installing Language Servers

Interactive Installation

Open Mason: :Mason
Navigate to the server you want (use j/k or / to search)
Press i to install
Wait for installation to complete (progress shows in UI)
Press q to close Mason

Example workflow:

:Mason
/typescript    (search for typescript)
i              (install typescript-language-server)
q              (quit when done)

Command-Line Installation

Install directly without opening the UI:

vim
:MasonInstall typescript-language-server
:MasonInstall lua-language-server
:MasonInstall pyright

Install multiple servers at once:

vim
:MasonInstall typescript-language-server html-lsp css-lsp json-lsp

Essential Language Servers

Here are the most commonly needed LSP servers organized by use case:

Web Development (JavaScript/TypeScript)

vim
:MasonInstall typescript-language-server
:MasonInstall tailwindcss-language-server
:MasonInstall eslint-lsp
:MasonInstall prettier

What they do:

typescript-language-server - Autocomplete, type checking, refactoring for TS/JS
tailwindcss-language-server - Tailwind CSS class autocomplete and validation
eslint-lsp - Linting and code quality checks
prettier - Code formatting

Web Fundamentals (HTML/CSS/JSON)

vim
:MasonInstall html-lsp
:MasonInstall css-lsp
:MasonInstall json-lsp

What they do:

html-lsp - HTML tag completion, validation
css-lsp - CSS property completion, validation
json-lsp - JSON validation, schema support

Lua (Neovim Configuration)

vim
:MasonInstall lua-language-server
:MasonInstall stylua

What they do:

lua-language-server - Autocomplete for Lua, Neovim API aware
stylua - Lua code formatter

Python

vim
:MasonInstall pyright
:MasonInstall ruff-lsp
:MasonInstall black

What they do:

pyright - Type checking, autocomplete, refactoring
ruff-lsp - Fast Python linting
black - Python code formatter

Rust

vim
:MasonInstall rust-analyzer

What it does:

rust-analyzer - Full Rust language support (autocomplete, diagnostics, macros)

Markdown

vim
:MasonInstall marksman
:MasonInstall markdown-toc

What they do:

marksman - Markdown link completion, navigation, diagnostics
markdown-toc - Generate table of contents

Shell Scripts

vim
:MasonInstall bash-language-server
:MasonInstall shellcheck
:MasonInstall shfmt

What they do:

bash-language-server - Bash/zsh script completion and diagnostics
shellcheck - Shell script linting
shfmt - Shell script formatting

Docker

vim
:MasonInstall dockerfile-language-server
:MasonInstall docker-compose-language-service

What they do:

dockerfile-language-server - Dockerfile syntax and best practices
docker-compose-language-service - Docker Compose YAML validation

YAML/TOML

vim
:MasonInstall yaml-language-server
:MasonInstall taplo

What they do:

yaml-language-server - YAML validation with schema support
taplo - TOML language support and formatting

Updating Language Servers

Update All Servers

vim
:MasonUpdate

Or in the UI:

:Mason
U    (capital U - updates all installed packages)

Update Single Server

In the Mason UI:

:Mason
/typescript    (navigate to server)
u              (lowercase u - update this package)

Or via command:

vim
:MasonUpdate typescript-language-server

Uninstalling Language Servers

Via UI

:Mason
/server-name    (navigate to installed server)
X               (capital X - uninstall)

Via Command

vim
:MasonUninstall typescript-language-server

Checking Installation Status

See All Installed Servers

vim
:Mason

Installed servers show a green checkmark (✓) in the UI.

Check Specific Server Status

vim
:MasonInstall typescript-language-server

If already installed, you'll see: "typescript-language-server" is already installed

Verify LSP is Running

Check if an LSP server is active for the current file:

vim
:LspInfo

This shows:

Which LSP servers are attached to the current buffer
Server status (running, stopped, etc.)
Server capabilities (formatting, hover, etc.)
Log file location for debugging

Troubleshooting

Server Won't Install

Problem: Installation fails with errors.

Solution:

Check the Mason log:
```
vim
:MasonLog
```
Common issues:
- Missing dependencies (Mason usually handles this, but some servers need system packages)
- Network issues (firewall blocking downloads)
- Insufficient disk space

Retry installation:

vim
:MasonUninstall server-name
:MasonInstall server-name

LSP Server Not Working After Installation

Problem: Server installed but not providing completions/diagnostics.

Solution:

Check if server is running:
```
vim
:LspInfo
```
Restart LSP:
```
vim
:LspRestart
```
Check file type: Some servers only activate for specific file types. Verify with:
```
vim
:set filetype?
```
Check LazyVim LSP config: Make sure the server is configured in LazyVim (usually automatic, but custom setups may need config)

Server Installed But Not in PATH

Problem: Server installed via Mason but not available in terminal.

This is normal! Mason installs servers in Neovim's data directory, not system-wide:

~/.local/share/nvim/mason/bin/

If you need system-wide access:

Add to your ~/.zshrc:

bash
# Add Mason binaries to PATH
export PATH="$HOME/.local/share/nvim/mason/bin:$PATH"

Then:

bash
source ~/.zshrc

Note: This is usually not needed - Mason servers are meant for Neovim use only.

Wrong Server Version

Problem: Need a specific version of a language server.

Solution:

Mason installs the latest stable version by default. To use a different version:

Uninstall current version:

vim
:MasonUninstall server-name

Install specific version:

Currently, Mason doesn't support version pinning directly. For specific versions, install manually:

bash
# Example: Install specific TypeScript version globally
npm install -g [email protected] typescript-language-server

Then configure LazyVim to use the global installation (see Mason configuration below).

Advanced Configuration

Customizing Mason in LazyVim

Create ~/.config/nvim/lua/plugins/mason.lua:

lua
return {
  {
    "williamboman/mason.nvim",
    opts = {
      -- Use system PATH first (prefer globally installed servers)
      PATH = "prepend",
      
      -- UI settings
      ui = {
        border = "rounded",
        width = 0.8,
        height = 0.8,
        icons = {
          package_installed = "✓",
          package_pending = "➜",
          package_uninstalled = "✗",
        },
      },
      
      -- Install these servers automatically
      ensure_installed = {
        "typescript-language-server",
        "lua-language-server",
        "html-lsp",
        "css-lsp",
        "json-lsp",
        "marksman",
      },
    },
  },
}

Key options explained:

PATH = "prepend" - Use global installations (npm/brew/etc.) before Mason's
ensure_installed - Auto-install these servers when LazyVim starts
ui.border - Change border style of Mason window

Auto-Install Servers on LazyVim Startup

To automatically install specific servers when LazyVim starts:

lua
return {
  {
    "williamboman/mason.nvim",
    opts = {
      ensure_installed = {
        -- Web dev
        "typescript-language-server",
        "tailwindcss-language-server",
        "html-lsp",
        "css-lsp",
        
        -- Config files
        "lua-language-server",
        "json-lsp",
        "yaml-language-server",
        
        -- Formatters
        "prettier",
        "stylua",
        
        -- Linters
        "eslint-lsp",
      },
    },
  },
}

Now when you launch LazyVim on a new machine, these servers install automatically.

Custom Server Configuration

Some LSP servers need custom configuration. Create ~/.config/nvim/lua/plugins/lsp.lua:

lua
return {
  {
    "neovim/nvim-lspconfig",
    opts = {
      servers = {
        -- TypeScript with custom settings
        tsserver = {
          settings = {
            typescript = {
              inlayHints = {
                includeInlayParameterNameHints = "all",
                includeInlayFunctionParameterTypeHints = true,
              },
            },
          },
        },
        
        -- Lua with Neovim API awareness
        lua_ls = {
          settings = {
            Lua = {
              workspace = {
                checkThirdParty = false,
              },
              diagnostics = {
                globals = { "vim" },
              },
            },
          },
        },
      },
    },
  },
}

Mason vs Manual Installation

Method	Pros	Cons
Mason	Automatic, isolated, easy updates, works everywhere	Limited version control
Homebrew	System-wide, version pinning	Manual PATH config, platform-specific
npm/pip/cargo	Version control, familiar	Dependency conflicts, manual setup
Bun	Fast, modern	Compatibility issues with some servers

Recommendation: Use Mason for everything unless you have a specific reason to install manually.

Quick Reference Commands

Installation

vim
:Mason                                  " Open UI
:MasonInstall server-name              " Install server
:MasonInstall server1 server2 server3  " Install multiple

Management

vim
:MasonUpdate                " Update all servers
:MasonUpdate server-name    " Update specific server
:MasonUninstall server-name " Remove server
:MasonLog                   " View installation logs

LSP Status

vim
:LspInfo       " Check running LSP servers
:LspRestart    " Restart LSP for current buffer
:LspStop       " Stop LSP for current buffer
:LspStart      " Start LSP for current buffer

Health Check

vim
:checkhealth mason    " Check Mason installation
:checkhealth lsp      " Check LSP configuration

Common LSP Server Names

Quick reference for Mason package names:

Language/Tool	Mason Package Name
TypeScript/JavaScript	`typescript-language-server`
Tailwind CSS	`tailwindcss-language-server`
HTML	`html-lsp`
CSS	`css-lsp`
JSON	`json-lsp`
Lua	`lua-language-server`
Python	`pyright` or `pylsp`
Rust	`rust-analyzer`
Go	`gopls`
Bash/Shell	`bash-language-server`
Markdown	`marksman`
Docker	`dockerfile-language-server`
YAML	`yaml-language-server`
Prettier (formatter)	`prettier`
ESLint (linter)	`eslint-lsp`

Search in Mason UI if you're not sure of the exact name - the search is forgiving.

Integration with LazyVim Workflows

Mason is just one piece of the LazyVim ecosystem:

Mason installs the language servers
nvim-lspconfig configures them
LazyVim provides keybindings and UI
nvim-cmp provides completions using LSP data

When you press:

gd - Go to definition (uses LSP server installed by Mason)
K - Hover docs (uses LSP server installed by Mason)
<Space>ca - Code actions (uses LSP server installed by Mason)

Everything just works because Mason, lspconfig, and LazyVim are tightly integrated.

Next Steps

Once you've installed language servers with Mason:

Learn LSP keybindings: See Installing LazyVim for essential shortcuts
Customize servers: See LazyVim LSP Configuration for advanced setup
Add formatters/linters: Use Mason to install tools like Prettier, ESLint, Black
Check server health: Run :checkhealth lsp to verify everything works

Managing LSP Servers with Mason

Managing LSP Servers with Mason

What Mason Does

Opening Mason

Mason UI Navigation

Installing Language Servers

Interactive Installation

Command-Line Installation

Essential Language Servers

Web Development (JavaScript/TypeScript)

Web Fundamentals (HTML/CSS/JSON)

Lua (Neovim Configuration)

Python

Rust

Markdown

Shell Scripts

Docker

YAML/TOML

Updating Language Servers

Update All Servers

Update Single Server

Uninstalling Language Servers

Via UI

Via Command

Checking Installation Status

See All Installed Servers

Check Specific Server Status

Verify LSP is Running

Troubleshooting

Server Won't Install

LSP Server Not Working After Installation

Server Installed But Not in PATH

Wrong Server Version

Advanced Configuration

Customizing Mason in LazyVim

Auto-Install Servers on LazyVim Startup

Custom Server Configuration

Mason vs Manual Installation

Quick Reference Commands

Installation

Management

LSP Status

Health Check

Common LSP Server Names

Integration with LazyVim Workflows

Next Steps

Links

Mason GitHub Repository

Mason Registry

nvim-lspconfig Documentation