# 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 [[2. Managing Homebrew with Brewfile]] for full workflow details. ## Essential LazyVim Keybindings LazyVim uses `Space` as the leader key. Here are the most important bindings: | Keybinding | Action | |------------|--------| | `<Space>` | Open Which Key menu (shows all available commands) | | `<Space>-f-f` | Find files (Telescope) | | `<Space>-f-g` | Live grep (search in files) | | `<Space>-e` | Toggle file explorer (Neo-tree) | | `<Space>-c-a` | Code actions (LSP) | | `<Space>-c-r` | Rename symbol (LSP) | | `<Space>-/` | Toggle terminal | | `<Space>-q-q` | Quit all | | `K` | Show hover documentation (LSP) | | `g-d` | Go to definition | **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) :Mason # Or install manually via Homebrew brew install lua-language-server brew install typescript-language-server brew install rust-analyzer ``` ### 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 | Feature | Plain Neovim | LazyVim | |---------|-------------|---------| | Setup time | Hours of config | 5 minutes | | Plugin management | Manual (Packer/lazy.nvim) | Pre-configured | | LSP setup | Complex | Automatic | | UI components | DIY | Beautiful defaults | | Keybindings | Custom from scratch | Sensible defaults | | Learning curve | Steep | Moderate (good docs) | **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](https://www.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]], [[2. 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]]