Neovim is a modern, extensible text editor that builds upon the legacy of Vim while introducing contemporary features and improved extensibility. This comprehensive guide will walk you through installing Neovim on macOS, setting up a powerful configuration with plugins, and customizing it for an optimal development experience.
Table of Contents
- Prerequisites
- Installing Homebrew
- Installing Neovim
- Setting Up Configuration
- Installing Plugin Manager
- Essential Plugins
- Complete Configuration
- Testing Your Setup
- Troubleshooting
- Next Steps
Prerequisites
Before we begin, ensure you have:
- macOS (any recent version)
- Terminal access
- Administrative privileges on your machine
- Basic familiarity with command-line operations
Installing Homebrew
Homebrew is the most popular package manager for macOS and provides the easiest way to install Neovim.
Step 1: Install Homebrew
Open Terminal and run the following command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
The installer will prompt you for your password and guide you through the installation process.
Step 2: Add Homebrew to PATH
After installation, you may need to add Homebrew to your system PATH. The installer will provide specific commands for your system, typically:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
Step 3: Verify Installation
Confirm Homebrew is installed correctly:
brew --version
You should see output showing the Homebrew version.
Installing Neovim
With Homebrew installed, installing Neovim is straightforward:
Step 1: Install Neovim
brew install neovim
Step 2: Verify Installation
Check that Neovim installed successfully:
nvim --version
You should see version information for Neovim.
Step 3: Create an Alias (Optional)
Many users prefer to use vim instead of nvim. Add this to your shell profile:
echo "alias vim='nvim'" >> ~/.zprofile
source ~/.zprofile
Setting Up Configuration
Neovim uses a configuration directory structure that's more organized than traditional Vim.
Step 1: Create Configuration Directory
mkdir -p ~/.config/nvim
Step 2: Create Configuration File
touch ~/.config/nvim/init.vim
Step 3: Open Configuration File
nvim ~/.config/nvim/init.vim
Installing Plugin Manager
We'll use vim-plug, a popular and lightweight plugin manager for Neovim.
Step 1: Install vim-plug
sh -c 'curl -fLo "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/autoload/plug.vim --create-dirs \
https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim'
Step 2: Verify Installation
Check that vim-plug was installed:
ls -la ~/.local/share/nvim/site/autoload/plug.vim
You should see the plug.vim file.
Essential Plugins
Here are the essential plugins that will transform your Neovim experience:
Core Plugins
- gruvbox: A popular color scheme with excellent contrast
- vim-airline: Enhanced status line with useful information
- NERDTree: File explorer sidebar
- auto-pairs: Automatic bracket and quote pairing
- vim-polyglot: Language pack for syntax highlighting
- coc.nvim: Intelligent code completion and LSP support
Development Plugins
- vim-fugitive: Git integration
- nerdcommenter: Easy code commenting
- vim-devicons: File type icons (requires Nerd Font)
Complete Configuration
Here's a comprehensive configuration that sets up Neovim with essential options and plugins:
" ================================
" Basic Settings
" ================================
" Clipboard integration
set clipboard=unnamedplus
" Completion menu behavior
set completeopt=noinsert,menuone,noselect
" Visual enhancements
set cursorline " Highlight current line
set number " Show line numbers
set cc=80 " Column guide at 80 characters
set title " Show file title in terminal
" Editing behavior
set hidden " Allow switching buffers without saving
set autoindent " Auto-indent new lines
set mouse=a " Enable mouse support
set inccommand=split " Show live preview of substitutions
" Window behavior
set splitbelow splitright " More natural split directions
" Performance
set ttyfast " Faster scrolling
" File type detection
filetype plugin indent on
syntax on
" Interface enhancements
set wildmenu " Enhanced command completion
set spell " Enable spell checking
" ================================
" Plugin Management
" ================================
call plug#begin(has('nvim') ? stdpath('data') . '/plugged' : '~/.vim/plugged')
" Color scheme
Plug 'morhetz/gruvbox'
" Status line and interface
Plug 'vim-airline/vim-airline'
Plug 'vim-airline/vim-airline-themes'
Plug 'ryanoasis/vim-devicons'
" File management
Plug 'scrooloose/nerdtree'
" Code editing
Plug 'scrooloose/nerdcommenter'
Plug 'jiangmiao/auto-pairs'
Plug 'sheerun/vim-polyglot'
" Code intelligence
Plug 'neoclide/coc.nvim', {'branch': 'release'}
" Git integration
Plug 'tpope/vim-fugitive'
call plug#end()
" ================================
" Plugin Configuration
" ================================
" Color scheme
colorscheme gruvbox
set background=dark
" Airline configuration
let g:airline_solarized_bg='dark'
let g:airline_powerline_fonts=1
let g:airline#extensions#tabline#enabled=1
let g:airline#extensions#tabline#left_sep=' '
let g:airline#extensions#tabline#left_alt_sep='|'
let g:airline#extensions#tabline#formatter='unique_tail'
" NERDTree configuration
let NERDTreeQuitOnOpen=1
let NERDTreeShowHidden=1
" ================================
" Key Mappings
" ================================
" Set leader key
let mapleader = ","
" Quick file explorer
nnoremap <leader>n :NERDTreeToggle<CR>
" Quick save
nnoremap <leader>w :w<CR>
" Quick quit
nnoremap <leader>q :q<CR>
" Split navigation
nnoremap <C-h> <C-w>h
nnoremap <C-j> <C-w>j
nnoremap <C-k> <C-w>k
nnoremap <C-l> <C-w>l
" Buffer navigation
nnoremap <leader>bn :bnext<CR>
nnoremap <leader>bp :bprevious<CR>
nnoremap <leader>bd :bdelete<CR>
Step-by-Step Configuration Setup
- Open your init.vim file:
nvim ~/.config/nvim/init.vim
Enter insert mode: Press
iPaste the complete configuration (copy from above)
-
Save and exit:
- Press
Esc - Type
:wand press Enter - Type
:qand press Enter
- Press
Installing Plugins
After adding the configuration:
Step 1: Restart Neovim
nvim ~/.config/nvim/init.vim
Step 2: Install Plugins
In Neovim, run:
:PlugInstall
This will open a split window showing the installation progress. Wait for all plugins to install.
Step 3: Restart Neovim
After installation completes:
- Press
qto close the plugin window - Type
:qto exit Neovim - Restart Neovim:
nvim
Testing Your Setup
Basic Functionality Tests
- Color scheme: Your editor should now have the Gruvbox dark theme
- Line numbers: Should be visible on the left
- Status line: Should show airline status bar at the bottom
- Column guide: A subtle line at column 80
Plugin Tests
- File explorer:
:NERDTree
Should open a file browser on the left
Auto-completion: Type some code and see intelligent suggestions
Git status: Open a git repository and see git information in the status line
Troubleshooting
Common Issues and Solutions
"Not an editor command: PlugInstall"
Cause: vim-plug wasn't installed correctly or Neovim needs to be restarted.
Solution:
- Verify vim-plug installation:
ls -la ~/.local/share/nvim/site/autoload/plug.vim
- Restart Neovim completely
- Source configuration:
:source ~/.config/nvim/init.vim
"Conflicting configs" Error
Cause: Both init.vim and init.lua exist in your config directory.
Solution:
rm ~/.config/nvim/init.lua
Color Scheme Not Working
Cause: Plugins haven't been installed yet.
Solution: Run :PlugInstall first, then restart Neovim.
Missing Icons or Fonts
Cause: Nerd Fonts not installed.
Solution: Install a Nerd Font:
brew tap homebrew/cask-fonts
brew install font-hack-nerd-font
Then configure your terminal to use the Nerd Font.
Verification Commands
Check your setup with these commands:
# Verify Neovim installation
nvim --version
# Check configuration file
cat ~/.config/nvim/init.vim
# Verify plugin manager
ls -la ~/.local/share/nvim/site/autoload/plug.vim
# Check installed plugins
ls -la ~/.local/share/nvim/plugged/
Next Steps
Advanced Configuration
Once you have the basic setup working:
- Language Servers: Configure coc.nvim for your programming languages
- Custom Keybindings: Add personal shortcuts for your workflow
- Additional Plugins: Explore fuzzy finders, git tools, and language-specific plugins
- Color Schemes: Try different themes like onedark, nord, or dracula
Learning Resources
-
Neovim Documentation:
:helpwithin Neovim -
Vim Tutor:
vimtutorcommand for interactive learning -
Plugin Documentation:
:help <plugin-name>for specific plugins
Backup Your Configuration
Consider version controlling your configuration:
cd ~/.config/nvim
git init
git add init.vim
git commit -m "Initial Neovim configuration"
Conclusion
You now have a fully functional Neovim setup with essential plugins and a solid foundation for further customization. This configuration provides syntax highlighting, file exploration, intelligent code completion, and a modern interface while maintaining Vim's powerful editing capabilities.
The modular nature of this setup allows you to add or remove plugins as your needs evolve. Start with this foundation and gradually customize it to match your specific development workflow.
Remember that mastering Neovim takes time and practice. Start with basic commands and gradually incorporate more advanced features as you become comfortable with the editor. The investment in learning Neovim will pay dividends in your productivity and coding efficiency.
Happy coding with Neovim!
Top comments (0)