Installing LazyVim

LazyVim is a pre-configured Neovim distribution that provides a modern IDE experience out of the box. Built on top of the lazy.nvim plugin manager, it includes sensible defaults, a curated set of plugins, and an extensible configuration system.

What LazyVim Provides

• Zero-config IDE features: LSP, completion, syntax highlighting, file explorer
• Modern UI: Beautiful statusline, tab bar, notifications
• Excellent defaults: Keybindings, color schemes, and workflow optimizations
• Easy extensibility: Add your own plugins and configs on top
• Fast startup: Lazy loading keeps Neovim responsive

Pre-Installation Checklist

Before installing LazyVim, ensure you have:

✅ Neovim 0.9.0 or later (LazyVim requires recent Neovim) ✅ Homebrew installed (macOS package manager) ✅ Git configured (for cloning plugin repositories) ✅ A Nerd Font installed (for icons in the UI) ✅ Backup of existing Neovim config (if you have one)

Installation Steps

Step 1: Install Neovim via Homebrew

bash
# Install latest Neovim
brew install neovim

# Verify installation
nvim --version

You should see version 0.9.0 or higher.

Step 2: Install a Nerd Font

LazyVim's UI uses icons that require a patched font. Install one via Homebrew:

bash
# Install JetBrainsMono Nerd Font (recommended)
brew install --cask font-jetbrains-mono-nerd-font

# Or install Hack Nerd Font
brew install --cask font-hack-nerd-font

# Or install FiraCode Nerd Font
brew install --cask font-fira-code-nerd-font

Configure Ghostty to use the Nerd Font:

Edit your Ghostty config:

bash
chezmoi edit "Library/Application Support/com.mitchellh.ghostty/config"

Add or update the font settings:

font-family = "JetBrainsMono Nerd Font"
font-size = 13

Apply the changes:

bash
chezmoi apply

Restart Ghostty to see the new font.

Step 3: Backup Existing Neovim Config

If you have an existing Neovim configuration, back it up:

bash
# Backup config directory
mv ~/.config/nvim ~/.config/nvim.backup

# Backup local state
mv ~/.local/share/nvim ~/.local/share/nvim.backup

# Backup cache
mv ~/.local/state/nvim ~/.local/state/nvim.backup

Step 4: Install LazyVim

Clone the LazyVim starter template:

bash
git clone https://github.com/LazyVim/starter ~/.config/nvim

Remove the .git folder so you can version control your own config:

bash
rm -rf ~/.config/nvim/.git

Step 5: Launch Neovim

Start Neovim to trigger the automatic plugin installation:

bash
nvim

LazyVim will:

1. Install the lazy.nvim plugin manager
2. Download and install all configured plugins
3. Set up LSP servers and treesitter parsers
4. Configure the UI components

This may take a few minutes on first launch. You'll see a dashboard showing installation progress.

Step 6: Verify Installation

Once installation completes, verify everything works:

1. Press Space to open the Which Key menu (shows available keybindings)
2. Press <Space>-f-f to open the file finder (Telescope)
3. Press <Space>-e to toggle the file explorer (Neo-tree)
4. Type :checkhealth to verify all components are working

Integrating with Ghostty

LazyVim works seamlessly with Ghostty's terminal emulation. Key features:

True Color Support

Ghostty automatically supports 24-bit true color, which LazyVim uses for syntax highlighting and themes.

No additional configuration needed - it just works.

Cursor Shape Changes

LazyVim changes cursor shape based on mode (block in normal, line in insert). Ghostty supports this via:

# In Ghostty config (already default)
shell-integration = true

Clipboard Integration

LazyVim uses the system clipboard for yank/paste operations. Ghostty handles this automatically.

• yy in normal mode → copies to macOS clipboard
• p → pastes from macOS clipboard
• Cmd+V → also works to paste

Font Rendering

Ghostty's font rendering is optimized for coding fonts. With a Nerd Font configured:

• Icons render correctly in Neo-tree file explorer
• Statusline symbols display properly
• LSP diagnostic icons appear as intended

Configuration Tips

LazyVim's config lives in ~/.config/nvim/. The directory structure:

~/.config/nvim/
├── lua/
│   ├── config/          # Your personal config
│   │   ├── autocmds.lua
│   │   ├── keymaps.lua
│   │   └── options.lua
│   └── plugins/         # Your plugin customizations
│       └── example.lua
├── init.lua             # Entry point (don't edit)
└── lazy-lock.json       # Plugin version lockfile

Adding Custom Keybindings

Edit ~/.config/nvim/lua/config/keymaps.lua:

lua
-- Example: Add custom keybinding
vim.keymap.set("n", "<leader>cf", function()
  vim.cmd("!prettier --write %")
end, { desc = "Format current file with Prettier" })

Installing Additional Plugins

Create a new file in ~/.config/nvim/lua/plugins/:

lua
-- ~/.config/nvim/lua/plugins/my-plugins.lua
return {
  -- Add a new colorscheme
  {
    "folke/tokyonight.nvim",
    opts = { style = "storm" },
  },
  
  -- Add a markdown preview plugin
  {
    "iamcco/markdown-preview.nvim",
    build = "cd app && npm install",
    ft = "markdown",
  },
}

Restart Neovim - LazyVim automatically detects and installs new plugins.

Customizing Options

Edit ~/.config/nvim/lua/config/options.lua:

lua
-- Example: Set relative line numbers
vim.opt.relativenumber = true

-- Set tab width to 4 spaces
vim.opt.tabstop = 4
vim.opt.shiftwidth = 4

-- Enable spell checking
vim.opt.spell = true

Managing the Brewfile

After installing Neovim and Nerd Fonts via Homebrew, update your Brewfile:

bash
# Regenerate Brewfile to include new packages
brew bundle dump --file=~/Brewfile --force

# Add to chezmoi
chezmoi add ~/Brewfile

# Commit changes
cd ~/.local/share/chezmoi
git add Brewfile
git commit -m "Add neovim and nerd fonts"
git push

See Managing Homebrew with Brewfile for full workflow details.

Essential LazyVim Keybindings

LazyVim uses Space as the leader key. Here are the most important bindings:

Pro tip: Press Space and wait - the Which Key menu shows all available commands grouped by category.

Troubleshooting

Icons Not Displaying

Problem: You see boxes or question marks instead of icons.

Solution: Ensure your Nerd Font is:

1. Installed via Homebrew (brew list | grep font)
2. Configured in Ghostty (font-family = "JetBrainsMono Nerd Font")
3. Applied with chezmoi apply
4. Active after restarting Ghostty

LSP Not Working

Problem: No autocomplete, diagnostics, or code actions.

Solution: Install language servers for your languages:

bash
# Install via Mason (within Neovim) - RECOMMENDED
:Mason

# Or install manually via Homebrew
brew install lua-language-server
brew install typescript-language-server
brew install rust-analyzer

Using Bun for LSP Servers

Can you use Bun instead of Node.js for LSP servers? Yes, but with caveats.

What works well with Bun:

• TypeScript Language Server
• HTML/CSS/JSON language servers (vscode-langservers-extracted)
• Pure JavaScript/TypeScript language servers

What might not work:

• Language servers using Node.js-specific APIs
• Servers with native dependencies compiled for Node.js

Recommended approach:

Option 1: Let Mason handle it (easiest)

Mason installs LSP servers in isolated environments and manages dependencies automatically. This is the most reliable approach and works regardless of whether you have Node.js or Bun installed.

vim
:Mason

Option 2: Install globally with Bun (for compatible servers)

bash
# TypeScript/JavaScript
bun install -g typescript-language-server typescript

# HTML, CSS, JSON
bun install -g vscode-langservers-extracted

# Verify installation
which typescript-language-server

Then configure Mason to use the global installations in ~/.config/nvim/lua/config/lazy.lua:

lua
{
  "williamboman/mason.nvim",
  opts = {
    PATH = "prepend", -- Use globally installed servers first
  },
}

Option 3: Hybrid approach (recommended for Bun users)

• Use Mason for most language servers (handles everything automatically)
• Install TypeScript/JavaScript-related servers with Bun if you prefer
• Let Mason fall back to its own installations for other languages

Bottom line: Mason is the easiest and most reliable method. Use Bun for global installations only if you have a specific reason and are comfortable troubleshooting compatibility issues.

Slow Startup

Problem: Neovim takes several seconds to start.

Solution:

1. Check which plugins are loading: :Lazy profile
2. Disable unused extras in ~/.config/nvim/lua/config/lazy.lua
3. Ensure plugins are lazy-loaded (check ft, cmd, keys in plugin specs)

Treesitter Parser Errors

Problem: Errors about missing parsers when opening files.

Solution: Install parsers manually:

bash
# In Neovim
:TSInstall python
:TSInstall javascript
:TSInstall rust

Comparison with Plain Neovim

When to use LazyVim:

• You want a modern IDE experience immediately
• You prefer sensible defaults over full customization
• You're new to Neovim or coming from VSCode

When to use plain Neovim:

• You want complete control over every aspect
• You have specific workflow requirements
• You enjoy building your config from scratch

Next Steps

Once LazyVim is installed:

1. Read the docs: :help LazyVim or visit lazyvim.org↗
2. Learn the keybindings: Press Space frequently and explore the Which Key menu
3. Install extras: Use :LazyExtras to add optional plugin packs (Python, Rust, etc.)
4. Customize gradually: Start with small tweaks in lua/config/ before adding plugins
5. Version control your config:

   bash
   cd ~/.config/nvim
   git init
   git add .
   git commit -m "Initial LazyVim setup"
   

Links

LazyVim Documentation

• URL: https://www.lazyvim.org/↗
• Summary: Official LazyVim documentation covering installation, configuration, keybindings, and plugin customization.
• Related: Neovim, Ghostty + tmux Startup Automation, Managing Homebrew with Brewfile

Nerd Fonts

• URL: https://www.nerdfonts.com/↗
• Summary: Collection of patched fonts with additional glyphs for icons. Essential for LazyVim's UI.
• Related: Ghostty + tmux Startup Automation

lazy.nvim Plugin Manager

• URL: https://github.com/folke/lazy.nvim↗
• Summary: Fast and flexible Neovim plugin manager that powers LazyVim's plugin system.
• Related: Neovim