Vim is a popular code editor on Unix\Linux systems, which is often compared with Emacs, another great code editor among programmers. The debate about which one is the best editor never cease. Vim is powerful. But it has its own shortcomings as an old editor1. Over the years, Vim’s code base has grown larger and larger, which is not good for maintenance and for adding new functionalities quickly. It has only one core developer, Bram Moolenaar, which is also not following the cooperation trend in open source projects. To overcome the shortcomings of Vim, preserve its advantages (compatible with Vim) and make the development of Vim faster, Neovim is born.

In this post, I will introduce how to install Neovim and configure it for Python development (in the following text, I will use Neovim and Nvim interchangeably).

Install Nvim

Neovim has pre-built executable appimage for Linux systems, you can download it from the Neovim GitHub release page. Put it under a directory in your home, for example, under directory ~/tools. After downloading this file, you need to give it execution right:

chmod u+x nvim.appimage

For easier use later, we can create a soft link for the appimage file and use nvim as the short name:

ln -s nvim.appimage nvim

Now, we need to add the Neovim install directory to the system PATH. Open .bash_profile and add the following line:

export PATH=$HOME/tools/nvim:$PATH

Save the file and source it to make the change take effect.

Now, Neovim has been installed on your system successfully. You can open neovim on terminal with nvim command.

Nvim configuration file

Neovim use a different configuration file from Vim. You need to create a file named init.vim under the directory ~/.config/nvim (if this directory does not exist, just create one). All configurations can be put into this file.

Most of the configuration options for Neovim are the same with Vim. You can copy your vim configurations if you have used Vim before.

Install and use plugin manager vim-plug

One of main reasons for the powerfulness of Vim comes from the vairous plugins written for it. With these plugins, you can achieve all sorts of crazy things which are hard to achieve with plain Vim. If you have installed a lot of plugins manually, you will find it difficult to manage them. Like Vim, Neovim does not have a builtin plugin manager. We need to install one ourselves.

There are two plugin managers in wide use among Nvim users. One is dein and the other is vim-plug. Vim-plug has a larger user base and seems more popular. Finally, I decided to give vim-plug a try.

Install vim-plug

  1. Install vim-plug itself:

    curl -fLo ~/.local/share/nvim/site/autoload/plug.vim --create-dirs \
    https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

After installing vim-plug, you may need to restart Nvim.

  1. Edit init.vim and add the configuration for vim-plug. I show an example configuration below (modified from the vim-plug GitHub page):

    call plug#begin('~/.local/share/nvim/plugged')
    
    Plug 'davidhalter/jedi-vim'
    
    call plug#end()

All the plugin installation command should be put inside the two call command. I will not repeat that later.

How to use vim-plug

You can execute following command in Nvim comand mode:

  • Install plugins::PlugInstall
  • Update plugins::PlugUpdate
  • Remove plugins::PlugClean (First, comment the plugin install command in init.vim. Open Nvim and use :PlugClean to uninstall plugins)
  • Check the plugin status::PlugStatus
  • Upgrade vim-plug itself::PlugUpgrade

Disable a plugin only temporarily

If you want to disable certain plugin for a while but do not want to delete it, you can try two methods:

  1. Comment out the plugin and reopen Nvim

  2. According to discussions here, to disable plugin foo/bar, you can use the following settings:

    Plug 'foo/bar', { 'on': [] }

Plugin install and settings

Auto-completion plugin deoplete

deoplete is an auto-completion plugin designed for Neovim:

Deoplete is the abbreviation of “dark powered neo-completion”. It provides an extensible and asynchronous completion framework for neovim/Vim8.

Strictly speaking, it is an auto-completion engine. In order to enable auto-completion for a certain programming language, you need to install the corresponding source.

Deoplete is easy to install. Use the following settings inside the vim-plug calls:

Plug 'Shougo/deoplete.nvim', { 'do': ':UpdateRemotePlugins' }

The minimum setting for deoplete is as follows:

let g:deoplete#enable_at_startup = 1

For more options and their meanings, check :h deoplete-options inside Nvim.

Install plugin deoplete-jedi

As I have said, deoplete supports auto-completion for various languages via different sources. In order to do auto-completion for Python, we need to install deoplete-jedi. In the following, I list the steps to install deoplete-jedi.

Step 1: Install dependency packages

First we need to install pynvim

pip install pynvim

We also need to install jedi. If you have already installed the latest version of Anaconda, jedi is already installed. Otherwise, you can install jedi via pip:

pip install jedi

Step 2: Install and set up deoplete-jedi

First, we need to install deoplete-jedi using vim-plug:

Plug 'zchee/deoplete-jedi'

After that, if nothing wrong happens, you can use auto-completion now! Open a Python source file with Nvim and start editing, you will see the auto-completion pop-up menu like what is shown in the following image:

How to use deoplete

  1. How to navigate between the items in the auto-completion list?

According to discussions here, you can navigate through the auto-completion list with <Ctrl-N> and <Ctrl-P>.

  1. How to automatically close the method preview window?

When we navigate through the auto-completion list, a small window will appear on top of current window and gives hints about the parameters of current selected method. But this window will not dieappear after auto-completion is done. According to discussions here, we can use the following setting to close the preview window automatically:

autocmd InsertLeave,CompleteDone * if pumvisible() == 0 | pclose | endif
  1. How can I open the preview window below the current window?

By default, preview windows will open on top of current window. You can change this behaviour by adding set splitbelow in the configuration file. For more info, see here.

  1. How can I navigate through the auto-completion list with Tab?

Add the following setting in the Nvim configuration file:

inoremap <expr><tab> pumvisible() ? "\<c-n>" : "\<tab>"

Status bar plugin: vim-airline

The default status bar of Nvim is simple and can not provide much useful information like Sublime Text or other modern code editors. However, the status bar can be customized to achieve wounderful effects. An excellent plugin is called vim-airline, which can achieve the same functionalities as Sublime Text status bar. It is easy to install:

Plug 'vim-airline/vim-airline'

Use :PlugInstall to install this plugin and restart Nvim. You should be able to see the new status bar with more information displayed.

Vim-airline status bar

Switch vim-airlinetheme

Vim-airline provides a lot of themes for you to customize your status bar. Check here to see what different theme looks like. Vim-airline has put the various themes in another plugin called vim-airlinetheme. To change the theme, we need to install this plugin:

Plug 'vim-airline/vim-airline-themes'

Then, in the Nvim configuration file, add the following settings:

let g:airline_theme='<theme>' " <theme> is a valid theme name

Automatic quote and bracket completion

When input quote and bracket, we often wish to input them as pairs. Nvim does not support this feature. Auto-pairs can achieve this and much more. Simply install it:

Plug 'jiangmiao/auto-pairs'

How to use

Let take an example on how to manipulate double quotes with this plugin. In insert model, press ", it will automatically become two double quotes. At the same time, the cursor is placed between the two double quotes, waiting for text input. When you have finished inputing text between the quotes, you may want to place the cursor after the right quote and continue inputing text. Here comes the magic part: just press " one more time and the cursor will be placed right behind the right quote.

comment plugin

Different programming languages have different specifications for comment. It would be great to change the comment style for the current file according to the detected file type. nerdcommenter is such a plugin. Install it with vim-plug:

Plug 'scrooloose/nerdcommenter'

To comment out a single line, use <leader>cc (leader is a prefix key in Nvim, the default leader key is /); to un-comment a line, use <leader>cu. To comment or uncomment several lines, add a repeating number to corresponding command, just like what you do in plain Vim. For more usages, check nerdcommenter’s documentaion

code auto-format plugin

neoformat can be used to format your source code. Install it with vim-plug:

Plug 'sbdchd/neoformat'

For Python code, you need to install a Python code formatter to work together with neoformat. We will choose yapf. First, we install this formatter with pip:

pip install yapf

Then, you can format Python code with yapf formatter using neoformat.

How to format code?

In command mode, input Neoformat, neoformat will auto-format your source code.

If neoformat can not detect your file type or you haven’t installed any formatter. You can add the following command to your Nvim configuration to let neoformat do some basic format for the file:

" Enable alignment
let g:neoformat_basic_format_align = 1

" Enable tab to spaces conversion
let g:neoformat_basic_format_retab = 1

" Enable trimmming of trailing whitespace
let g:neoformat_basic_format_trim = 1

There is another format plugin vim-autoformat which you can try.

Code jump (go-to) plugin

We often need to jump to the definition of class and method to check their implementation details. We can use jedi-vim to achieve this. Actually, jedi-vim can also do code auto-completion. Since we have installed deoplete and deoplete-jedi, we can disable code completion and only use the code jumpt function of jedi-vim. Install jedi-vim with vim-plug:

Plug 'davidhalter/jedi-vim'

Use the following simple configuration:

" disable autocompletion, cause we use deoplete for completion
let g:jedi#completions_enabled = 0

" open the go-to function in split, not another buffer
let g:jedi#use_splits_not_buffers = "right"

How to use jedi-vim

Move the cursor to the class or method you want to check, then press the various supported shortcut provided by jedi-vim:

  • <leader>d: go to definition
  • K: check documentation of class or method
  • <leader>n: show the usage of a name in current file
  • <leader>r: rename a name

File managing and exploration plugin

Nerdtree file navigation window

Those who have been working with GUI code editors are familiar with the sidebar on the left side of the code editor, which provides an overview of files and folders in current project. How do we achieve similar functions in Nvim? You can use nerdtree. First, install it using vim-plug:

Plug 'scrooloose/nerdtree'

How to use nerdtree?

  1. How to open file navigation window?

In command mode, input :NERDTree to open the directory your current file resides.

  1. How do I open a file in the file explorer?

Place the cursor in the file you want to open and press o to open this file in the right window.

  1. How do I switch between file window and nerdtree file navigation window?

This is the same as how you switch windows in Vim. Press ctrl and press w two times quickly to switch window. You can also press <Ctrl-w> and then press L.

  1. How do I exit or close file explorer window?

Press q while your cursor is this window? Or use NERDTreeClose command in command mode.

For more customization, refer to this post.

Code checker plugin

Neomake is a tool for code syntax check and build automation for Nvim. Install it with vim-plug:

Plug 'neomake/neomake'

Neomake’s syntax check for various languages relies on various linters. After installation, you need to install linters according to your programming languages. The linter for different languages are listed here.

For Python, we can use pylint as linter. Install pylint with pip or conda:

conda install pylint
# pip install pylint

After installing pylint, we need to set it in init.vim as the Python code checker:

let g:neomake_python_enabled_makers = ['pylint']

Code checking

In command mode, use Neomake command to start syntax check. We can also enable automatical code check. Just add the following setting in Nvim configuration file:

call neomake#configure#automake('nrwi', 500)

Pylint checks extensively on your code, which makes it a bit slow. Another code linter you can try is flake8, which is faster.

Multiple cursor editting plugin

If you have used Sublime Text before, you must be impressed by Sublime Text’s ability to edit multiple position in the code simultaneously. This function is great when you want to refactor your code. You can achieve smiliar function with the help of vim-multiple-cursors. Install it with:

Plug 'terryma/vim-multiple-cursors'

How to use

In normal mode, move the cursor to a variable you want to rename, press <Ctrl-N> and this varialbe will be highlighted. Continue press <Ctrl-N>, the next occurance of this variable will be highlighted. If you want to skip a certain occurance (for example, a string may contain a sub-string which is the same as the variable), just press <Ctrl-X> after this position has been highlighted. Continue selecting the occurance of this variable until all its occurances has been selected.

Now, press c (in Nvim, c means to change ) and enter insert mode. Input a new name and save.

But, I should say that this plugin is not perfect. When you have a lot of occurances of the variable in the file, the refactor of variable name is slow.

There are some discussions about Neovim’s native support for multiple cursors. But it seems that this function is still not finished as of today. You can find relevant discussions in the following links:

Highlight your yank aera

In Nvim, if you yank (i.e., copy) a block of text, you do not get a visual hint about exactly what you have copyed. Unless you are very familiar with Nvim, you may have copied less or more than what you want to copy, which is annoying. With the help of vim-highlightedyank, you can now highlight the text region which you have yanked. Handy little feature, isn’t it?

You can install it with vim-plug:

Plug 'machakann/vim-highlightedyank'

Most of the times, you do not need any further settings after installing this plugin. But, for some colorschemes, you will not be able to see the highlight colors. To fix this issue, add the following setting to Nvim configuration:

hi HighlightedyankRegion cterm=reverse gui=reverse

If you feel that the highlight duration time is too short, you can increase the highlight duration (measured in ms):

" set highlight duration time to 1000 ms, i.e., 1 second
let g:highlightedyank_highlight_duration = 1000

Code folding plugin

For large code base, it is helpful to fold some part to get a better idea of the structure of the code. SimplyFold is nice plugin for code folding. Install it with vim-plug:

Plug 'tmhedberg/SimpylFold'

You do not need furthur settings. It works out of the box.

simple usage

There are some shortcut to manipulate code folding:

  • zo: Open fold in current cursor postion
  • zO: Open fold and sub-fold in current cursor postion recursively
  • zc: Close the fold in current cursor position
  • zC: Close the fold and sub-fold in current cursor position recursively

Theme install and configuration

Before we begin

Neovim has several bulitin colorschemes or themes. You may not like them and want better themes. It is easy to install a theme. But it is little tricky to make the theme display correctly as what the theme homepage shows. A lot of themes will not display well if you use a SSH client which has poor support for true colors. For Windows system, after trying several SSH clients, I find that ZOC works best. For Mac, you can use the open source tool iTerm2. To find more SSH clients which support true colors, visit this page.

Install themes

Gruvbox is a popular Vim colorscheme. Install it with vim-plug:

Plug 'morhetz/gruvbox'

Then use :PlugInstall to install it just like you install other plugins.

In Nvim configuration file, activate this theme with the following setting:

colorscheme gruvbox

It has two modes, i.e., dark and light, which can be switched using the following settings:

set background=dark " use dark mode
" set background=light " uncomment to use light mode

Restart Nvim and you will activate the new theme. It looks like the following on my Mac:

gruvbox theme

Other themes

There are other themes you may want to try:

How do I change the font?

Unlike Sublime Text, you can not set up which font to use in Nvim configuraton. Nvim will automatically use the font you choose for the terminal client. So you need to set up your favorite font in the terminal. Some of the good programming font are:

How to find more interesting plugins?

There is website vimawesome which collects information about various Vim plugins. You can find helpful plugins on this website.

Since most Vim plugins are published on GitHub, you can also search with vim and other keywords on GitHub to find relevant plugins. For example, search vim colorschem or vim theme to find themes designed for Vim.

Builtin terminal

Neovim has support for terminal emulator so that you can directly run a shell inside Neovim. It is handy for temporary shell operations.

To open the terminal, use :terminal or :vnew term://bash or new term://bash. After entering the terminal, you are in normal mode. Press i to start typing terminal command.

To exit insert mode in terminal emulator, press <Ctrl+\><Ctrl+N>.

To exit terminal emulator and close the window, use exit.

The difference between Nvim and Vim

Support for bracketed paste mode

Neovim has support for bracketed paste mode. The paste option in Vim is obsolete. Use :h paste and you will the following documentation:

This option is obsolete; bracketed-paste-mode is built-in.

Neovim is all nocompatible

In Nvim normal mode, use :h comatible, and you will see that:

Nvim is always “nocompatible”

For more differences between Nvim and Vim, see here.

Trouble shooting

In this part, I introduce some issues found when using Nvim and how to fix these issue.

Nvim colorscheme does not look normal inside Tmux

If your terminal supports true color, first install the latest version of tmux, add the following config to ~/.tmux.conf (extracted from here)

set -g default-terminal "screen-256color"
set -ga terminal-overrides ",xterm-256color*:Tc"

Then the color should be fine. Otherwise, in the Nvim config file init.vim, use the following setting instead:

set notermguicolors

Also, there are some discussions here.

How do I get a log file when starting Neovim

Use nvim -VNUMnvim.log. NUM is used to indicate verbose level, for example:

nvim -V10nvim.log

will create a log file nvim.log with verbose level 10.

More reference here. See also nvim --help.

Ok, that is end of this long post. You can find my complete Nvim configurations here. Happy coding!


  1. Vim was first released in 1991. Its predecessor is Vi, born in 1978.