Installing neovim nightly alongside stable

Nvim v0.5 is the development branch of neovim and has been in constant feature update. Some of the major features include (but still in development):

• built-in Language Server Client (aka nvim-lsp)
• treesitter (used for syntax highlighting - and a bit of syntax check, but a topic for another day perhaps)
• init.lua as a substitute config file instead of init.vim (Also coming soon in a future post)

You can have a look at their roadmap here to see what else is in development.

But today, my focus will be on installing nightly (or v0.5, but for this post I will refer to as nightly) alongside your stable version.

Why two different versions and not just update to nightly?

It's true you can just update to the nightly version and it will still work with your current config and go about your day. But, for someone like me who uses vim at work, I want to keep a stable version separate to the nightly where I may encounter breaking changes.

I also want to try out the features from nightly and mess around but rather keep those separate to my stable config.

If you also use vim at work but also want to experiment with the new features from nightly, then read on. Else you would most likely not care about the majority of this post, but feel free to read 🙂.

Requirements

Couple resources and tools you may need before we get started will be listed here:

Tools:

• git
• Build prerequisites from neovim wiki

We will also make heavy use of the Build section of the neovim wiki resource:

• Building Neovim

Clone and Build

Once you have git and the build pre-requisites installed, we can continue and clone the neovim repo into your machine. These instructions are mostly for linux but they are similar for a Mac and for Windows (if you use WSL). My default directory will be the $HOME directory. So let's clone and cd into it.

git clone https://github.com/neovim/neovim.git $HOME/neovim
cd $HOME/neovim

Next we compile the source, let's keep it a Release type because our focus is using neovim and not developing it:

make CMAKE_BUILD_TYPE=Release

Depending on your machine, this may take anywhere from 30 seconds to an hour or two. But eventually, if all goes well you should get no error messages and be able to see the executable at build/bin.

Setup

Now we can also install the binary in a location of choice (by running make CMAKE_INSTALL_PREFIX=/path/to/location install, but I would prefer to just leave the binary at build/bin/nvim and work from there. The downside is that we will need to provide the runtime explicitly, so we run:

VIMRUNTIME=runtime ./build/bin/nvim

Congratulations! You got vim successfully compiled and running 🎉🥳🎉

At this point you are done. But writing the above line every time you want to open nightly is quite a hassle, especially when you want to open from your project directory but the runtime directory is not relative to your project, so you will have to explicitly include the full path to the runtime and the neovim binary.

A better way, would be to create a script file and call that instead. So let's make one!

touch $HOME/.local/bin/nv.sh
chmod u+x $HOME/.local/bin/nv.sh

A quick note, it is convention that when making script file you create it with the .sh extension, but you can omit that and just use the script name (like nv instead of nv.sh).

Now inside nv.sh:

# nv.sh
VIMRUNTIME=$HOME/neovim/runtime $HOME/neovim/build/bin/nvim

Assuming that $HOME/.local/bin is in your $PATH environment, calling nv.sh anywhere from your terminal should open neovim nightly.

Config

Add your config at $HOME/.config/nvim/init.vim and have two separate configs for stable and nightly.

" init.vim

let $NVIM_CONFIG_DIR = expand('$HOME/.config/nvim')

if has('nvim-0.5')
    " nightly config
    source $NVIM_CONFIG_DIR/nightly.vim
else
    " stable config
    source $NVIM_CONFIG_DIR/stable.vim
endif

Then you can have a stable.vim for your stable config and then nightly.vim for your nightly config.

---

However, we can take this a step further and separate them in different directories. So you can have a stable config at $HOME/.config/nvim and have your nightly config at $HOME/.config/nvim-nightly. While this works, there are a couple more tweaks you will have to do in order for it to work properly. If you are interested in this method then I would recommend you to read the next section, otherwise just jump to updating neovim nightly further below 😜.

Separate directory for stable and nightly (OPTIONAL)

Now everything from here onward is optional for you to do. The reason why I did this is because I had issues with loading remote plugins (plugins with rplugin directory) where it would over-write the rplugin.vim manifest, if I switch between stable and nightly. This was due to me having different plugins for the two versions.

The solution was to keep them in separate directory so there are no namespace clashes. So we should have the following directory structure for stable (nvim) and nightly (nvim-nightly).

$HOME/.config/
├── nvim
│   └── init.vim
├── nvim-nightly
│   └── init.vim

The same for the local directory:

$HOME/.local/share/
├── nvim
│   ├── site/
│   └── rplugin.vim
├── nvim-nightly
│   ├── site/
│   └── rplugin.vim

Update nv.sh

Since nvim/init.vim is the file neovim looks for as the default config, we need to explicitly mention the config file we want loaded for nightly. And we also want to specify where remote plugins manifest will be placed.

# nv.sh
NVIM_RPLUGIN_MANIFEST=$HOME/.local/share/nvim-nightly/rplugin.vim VIMRUNTIME=$HOME/neovim/runtime $HOME/neovim/build/bin/nvim "$@" -u $HOME/.config/nvim-nightly/init.vim

Edit: Added the $@ after the nvim executable. I've noticed that if you pass a file name to the script it will not load it. We want to be able pass down any number of arguments from the script to the executable.

Add custom paths to runtimepath

Finally, we need to specify our config and local directory to be part of the runtimepath, else it will end up not picking plugins installed via a plugin manager. So within the config file, we want to remove all instances where we don't want runtimepath to search for and explicitly add our own custom path.

" $HOME/.config/nvim-nightly/init.vim

set runtimepath-=~/.config/nvim
set runtimepath-=~/.config/nvim/after
set runtimepath-=~/.local/share/nvim/site
set runtimepath-=~/.local/share/nvim/site/after

set runtimepath+=~/.config/nvim-nightly/after
set runtimepath^=~/.config/nvim-nightly
set runtimepath+=~/.local/share/nvim-nightly/site/after
set runtimepath^=~/.local/share/nvim-nightly/site

Add custom paths to packpath if using minpac or similar plugin manager

If you are using the native package handler, or using a plugin manager that utilizes the build-in package handling in vim like minpac. Then you may have to specify the custom path to your local directory.

" $HOME/.config/nvim-nightly/init.vim

set packpath-=~/.config/nvim
set packpath-=~/.config/nvim/after
set packpath-=~/.local/share/nvim/site
set packpath-=~/.local/share/nvim/site/after

set packpath^=~/.config/nvim-nightly
set packpath+=~/.config/nvim-nightly/after
set packpath^=~/.local/share/nvim-nightly/site
set packpath+=~/.local/share/nvim-nightly/site/after

Update neovim nightly

To update neovim, it's as easy as pulling all the latest changes to your local machine and doing a clean compile.

cd $HOME/neovim
git pull
make distclean && make CMAKE_BUILD_TYPE=Release

Conclusion

I hope this guide helps you in setting up neovim nightly alongside the stable version, or at least to helps me reference in-case I forget. It is one of many ways of getting them installed in a machine, but this is the way I preferred on getting it installed.

Troubleshooting

E149: Sorry, no help for ...

If you have problems accessing docs, since it was compiled from source you will have to manually generate docs. Fortunately, this can be done just once by running the vim ex command:

:helptags $VIMRUNTIME/doc

$MYVIMRC is empty

Some might use :e $MYVIMRC to open their config file, and because we are using different directory for configs, you may have to include MYVIMRC variable in nv.sh.

# nv.sh
MYVIMRC=$HOME/.config/nvim-nightly/init.vim NVIM_RPLUGIN_MANIFEST=$HOME/.local/share/nvim-nightly/rplugin.vim VIMRUNTIME=$HOME/neovim/runtime $HOME/neovim/build/bin/nvim "$@" -u $HOME/.config/nvim-nightly/init.vim

packer.nvim uses default nvim directory and not the separate ~/.config/nvim-nightly and ~/.local/share/nvim-nightly directory

If you followed the guide that separates the directories and use packer plugin manager for nvim nightly then you may want to add packer.init() before your packer.startup() and specify the nvim-nightly directory instead of the default directory. You can use my plugins file as an example. Below is a snippet of it:

require 'packer'.init {
  package_root = os.getenv('HOME') .. '/.local/share/nvim-nightly/site/pack',
  compile_path = os.getenv('HOME') .. '/.config/nvim-nightly/plugin/packer_compiled.vim'
}

require 'packer'.startup(function(use)
  -- plugins
end)

Comments

[Jake Vincent]

Thank you, this is helpful! I found this after giving up on having two separate installations but was still struggling to use two separate config and data directories for an older setup with init.vim and a newer setup with init.lua. I could get everything to work except that I couldn't get paq-nvim to install packages anywhere but ~/.local/share/nvim, when I wanted it to install them in ~/.local/share/nvim-lua (it's less configurable than packer and only refers to stdpath("data")).

What I ended up doing was the following:

• creating ~/.local/share-nvim
• symlinking my nvim-lua data directory in ~/.local/share to ~/.local/share-nvim as nvim
• setting up an alias nvim.paq that opens nvim with init.lua and sets the data directory to ~/.local/share-nvim (by setting the XDG_DATA_HOME env variable) and only installing/updating packages with this instance of nvim
• setting up a separate alias nvim.lua that uses the init.lua config but doesn't change XDG_DATA_HOME

It's very hacky, but with the above, and with runtimepath and packpath settings based on what you suggest above, I can get Paq to install packages to ~/.local/share/nvim-lua indirectly via the symlink and get nvim to use those packages. I would just always set XDG_DATA_HOME to the special data directory when I want to use init.lua, but I get some weird issues compiling TeX documents when XDG_DATA_HOME is changed.

[Arnold Chand]

Hey!

This is nice! But a bit overly complicated, and I guess that's one of the limitations of keeping separately namespaced nvim configs that would lead to doing the hacky way you provided. Don't get me wrong that's a nice implementation 🙂

Although here is something you can try with paq-nvim if you have the time. I've checked through paq-nvim docs and, while a bit obscure, there is a way to change where to install the plugins, and that is thru the setup() function.

Make sure you git clone paq-nvim to the correct directory that was set in your packpaths, following your folder convention:

git clone --depth=1 https://github.com/savq/paq-nvim.git \
    "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim-lua/site/pack/paqs/start/paq-nvim

Before you provide your plugins within paq, you need to call the setup function and provide the path there, following your folder convention:

local paq = require 'paq-nvim'

paq.setup {
  path = vim.env.HOME .. '/.local/share/nvim-lua/site/pack/paqs/'
}

paq {
  'savq/paq-nvim';

  -- your plugins below
}

I have not tried this myself so do let me know if this helps out or not with keeping your configs separate with different directories.

[Johnny M. Salas]

Pretty useful

This was my vim alias: `alias vim='VIMRUNTIME=$HOME/neovim/runtime $HOME/neovim/build/bin/nvim'

Some extra steps, in my case:

In Mac:
I had to brew install cmake and automake

Then, In Ubuntu:
apt-get install automake libtool libtool-bin gettext

[Arnold Chand]

This is awesome! I forgot you could make an alias as well, the reason I kept it as a sh file was because I was leading up to separating your stable neovim config from nightly neovim config, so I just stuck to that lol

As for your extra steps, was that not detailed in the neovim wiki that was provided in the post? github.com/neovim/neovim/wiki/Buil...

If not you could help contribute to their wiki in case some users might also have to install the same packages.

[Matteo Hertel]

This is a great post thank you so much for sharing, I really wanted to check out 0.5 but I could not risk messing up my setup!

just a note: in the init.vim there is a missing endif at the end, without it neovim will throw an error

should be

" init.vim

let $NVIM_CONFIG_DIR = expand('$HOME/.config/nvim')

if has('nvim-0.5')
    " nightly config
    source $NVIM_CONFIG_DIR/nightly.vim
else
    " stable config
    source $NVIM_CONFIG_DIR/stable.vim
endif

Thanks again!

[Arnold Chand]

Thanks for that, I've updated the post 😅

[弱鸡]

Thanks for making the post

[Ildar]

github.com/iledarn/nix-neovim

Thx! I did wrap the solution in Nix. So I can install all with one command - nix-shell and it wouldn't conflict with my existing Neovim.

[eeeeixix]

When I try to run the stable version of nvim I get an error 'E484 Can't open file ~/.config/nvim/stable.vim' . I am not sure what is causing it and was wondering if someone could help?

[Arnold Chand]

Hey, so this article was written a long long time ago and neovim has changed a lot of stuff since then. If you want to keep two separate I would suggest to look at NVIM_APPNAME (neovim.io/doc/user/starting.html#%...) and this article has a good guide on how to use it: michaeluloth.com/neovim-switch-con...

That being said, my guess for your problem where the file can't be opened is probably because you haven't specified the proper path.

Maybe try expanding the path with expand('~/.config/nvim/stable.vim') or use stdpath('config') . '/stable.vim'