nvs (Neovim Version Switcher)

Neovim Version Switcher – Easily install, switch, and manage multiple versions (including commit hashes) and config of Neovim like a boss 🚀

👀 Overview

nvs (Neovim Version Switcher/Manager) is a lightweight cross-platform CLI tool written in Go 🏗️ that makes it super easy to install, switch between, and manage multiple versions of Neovim and config on your machine. Whether you’re testing a cutting‑edge nightly build 🌙 or sticking with the stable release 🔒, nvs has got your back!

$ nvs use stable
✓ Switched to Neovim stable

$ nvim -v
NVIM v0.10.4
Build type: Release
LuaJIT 2.1.1713484068
Run "nvim -V1 -v" for more info

$ nvs use nightly
✓ Switched to Neovim nightly

$ nvim -v
NVIM v0.11.0-dev-1961+g7e2b75760f
Build type: RelWithDebInfo
LuaJIT 2.1.1741571767
Run "nvim -V1 -v" for more info

$ nvs install 0.10.0
ℹ Resolving version v0.10.0...
ℹ Installing Neovim v0.10.0...
✓ Installation successful!

$ nvs use 0.10.0
✓ Switched to Neovim v0.10.0

$ nvim -v
NVIM v0.10.0
Build type: Release
LuaJIT 2.1.1713484068
Run "nvim -V1 -v" for more info

🌟 Showcase

nvs-demo.mp4

🌟 Features

• Easy Installation: Download and install Neovim versions directly from GitHub with a single command.
• Version Switching: Switch between installed versions in a snap. nvs updates a global symlink so your preferred version is always just a command away.
• Config Switching: Easily toggle between Neovim configurations by scanning ~/.config (including symlinks) and setting NVIM_APPNAME interactively or via a direct subcommand argument.
• Remote Version Listing: List all available remote releases (stable, nightly, etc.) with cached results to avoid GitHub rate limits ⚡. Need fresh data? Just add the force flag.
• Upgrade for Stable and Nightly: Easily upgrade your installed stable and/or nightly versions. The upgrade command checks if you’re already on the latest version and only performs an upgrade if needed.
• Uninstallation & Reset: Remove individual versions or reset your entire configuration with ease.
• Cross-Platform: Works on macOS (Intel & Apple Silicon), Linux, and Windows.
• Verbose Logging: Run with the --verbose flag to see detailed logs during directory initialization, reset, and other operations.

🚀 Installation

Warning

To make the process butter smooth, remember to remove any Neovim installation in your system and let nvs manage them instead.

Using our install script

You can install nvs with a single command that downloads and executes our installation script. The script automatically detects your operating system and architecture and installs the appropriate binary.

Warning

Always review remote scripts before execution. Before running any script from the internet, inspect its contents to ensure its safety.

curl -fsSL https://raw.githubusercontent.com/y3owk1n/nvs/main/install.sh | bash

Note

You can upgrade by just running the same installation script again.

We have also included an uninstall script if you would like to uninstall it

curl -fsSL https://raw.githubusercontent.com/y3owk1n/nvs/main/uninstall.sh | bash

Homebrew

Install nvs via Homebrew! Simply add our tap:

brew tap y3owk1n/tap

Then install with:

brew install y3owk1n/tap/nvs

Using a released binary

• Download the latest release binary for your system
• Make it available globally on PATH environment variable
• Run it like any other method

Building From Source

Make sure you have Go (v1.23 or later) installed. Then run:

git clone https://github.com/y3owk1n/nvs.git
cd nvs
mkdir -p build

# Build for darwin-arm64
env GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -ldflags "-s -w -X github.com/y3owk1n/nvs/cmd.Version=local-build" -trimpath -o ./build/nvs-darwin-arm64 ./main.go

# Build for darwin-amd64
env GOOS=darwin GOARCH=amd64 CGO_ENABLED=0 go build -ldflags "-s -w -X github.com/y3owk1n/nvs/cmd.Version=local-build" -trimpath -o ./build/nvs-darwin-amd64 ./main.go

# Build for linux-arm64
env GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -ldflags "-s -w -X github.com/y3owk1n/nvs/cmd.Version=local-build" -trimpath -o ./build/nvs-linux-arm64 ./main.go

# Build for linux-amd64
env GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags "-s -w -X github.com/y3owk1n/nvs/cmd.Version=local-build" -trimpath -o ./build/nvs-linux-amd64 ./main.go

# Build for windows-amd64
env GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -ldflags "-s -w -X github.com/y3owk1n/nvs/cmd.Version=local-build" -trimpath -o ./build/nvs-windows64.exe ./main.go

Move the binary to your PATH or run it directly.

📂 Configuration & Data

nvs now follows OS-specific best practices for storing configuration, cache, and binary data. By default:

• Configuration Files: Stored in ~/.config/nvs on Unix-like systems (or %APPDATA%\nvs on Windows). Override with the NVS_CONFIG_DIR environment variable.
• Cache Files: Stored in ~/.cache/nvs on Unix-like systems (or %LOCALAPPDATA%\nvs\Cache on Windows). Override with the NVS_CACHE_DIR environment variable.
• Global Binary Symlinks: Placed in ~/.local/bin on Unix-like systems (or an equivalent directory on Windows). Override with the NVS_BIN_DIR environment variable.

Note

All these directories will be created upon running any command (including nvs --help) the first time after installation. If you set custom paths after that, feel free to manually delete the default directories.

Overriding Default Directories with Environment Variables

nvs allows you to customize the locations where configuration, cache, and binary files are stored by setting the following environment variables:

• NVS_CONFIG_DIR Overrides the default configuration directory.
  • Default:
    • On Unix-like systems: ~/.config/nvs
    • On Windows: %APPDATA%\nvs
• NVS_CACHE_DIR Overrides the default cache directory.
  • Default:
    • On Unix-like systems: ~/.cache/nvs
    • On Windows: %LOCALAPPDATA%\nvs\Cache
• NVS_BIN_DIR Overrides the default global binary directory.
  • Default:
    • On Unix-like systems: ~/.local/bin
    • On Windows: %APPDATA%\nvs\bin

How to Set These Environment Variables

On Unix-like Systems (Linux/macOS)

You can add the following lines to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc):

# Override nvs directories
export NVS_CONFIG_DIR="$HOME/custom-config/nvs"
export NVS_CACHE_DIR="$HOME/custom-cache/nvs"
export NVS_BIN_DIR="$HOME/custom-bin"

After editing your configuration file, reload it:

source ~/.bashrc   # or source ~/.zshrc

On Windows

You can set environment variables temporarily in the Command Prompt:

set NVS_CONFIG_DIR=C:\Path\To\Custom\Config
set NVS_CACHE_DIR=C:\Path\To\Custom\Cache
set NVS_BIN_DIR=C:\Path\To\Custom\Bin

For a permanent change, open the System Properties → Advanced → Environment Variables and add or edit the variables there. Alternatively, you can use the setx command in an elevated Command Prompt:

setx NVS_CONFIG_DIR "C:\Path\To\Custom\Config"
setx NVS_CACHE_DIR "C:\Path\To\Custom\Cache"
setx NVS_BIN_DIR "C:\Path\To\Custom\Bin"

Note

If you override the binary directory (NVS_BIN_DIR), make sure to update your system's PATH variable accordingly so that the nvs binaries can be found by your shell.

💻 Usage

nvs uses a clean subcommand interface. Run nvs --help for full details.

Commands

A CLI tool to install, switch, list, uninstall, and reset Neovim versions.

Usage:
  nvs [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      Switch Neovim configuration
  current     Show current active version with details
  env         Print NVS env configurations
  help        Help about any command
  install     Install a Neovim version or commit
  list        List installed versions
  list-remote List available remote versions with installation status (cached for 5 minutes or force)
  path        Automatically add the global binary directory to your PATH
  reset       Reset all data (remove symlinks, downloaded versions, cache, etc.)
  uninstall   Uninstall a specific version
  upgrade     Upgrade installed stable and/or nightly versions
  use         Switch to a specific version or commit hash

Flags:
  -h, --help      help for nvs
  -v, --verbose   Enable verbose logging
      --version   version for nvs

Use "nvs [command] --help" for more information about a command.

list-remote

List available remote releases and installed status (cached for 5 minutes to avoid rate limiting). Use the force flag to refresh the cache.

Note

The list will be filtered out for only nightly, stable, and all version that are above v0.5.0.

nvs list-remote
nvs list-remote force # force refresh the cache

# or with shorthand
nvs ls-remote
nvs ls-remote force

list

List all locally installed Neovim versions

nvs list

# or with shorthand
nvs ls

install

Install a specific Neovim version or build from commits.

Warning

To build from commit, make sure your system has git, make, and cmake installed, as building Neovim requires these 3 pieces to work together.

Warning

If you're using macos make sure to also run brew install ninja cmake gettext curl.

nvs install stable    # Install the latest stable release 🔒
nvs install nightly   # Install the latest nightly release 🌙
nvs install v0.10.3   # Install a specific version
nvs install 0.10.3    # Or without the v keyword
nvs install master    # Build and install based on the latest master commit
nvs install 2db1ae3   # Build and install a specific commit hash in 7 character
nvs install 2db1ae37f14d71d1391110fe18709329263c77c9 # Or a 40 character hash

# or with shorthand
nvs i stable

use

Switch to a particular version. This updates a global symlink in your designated bin directory so that you can simply run nvim.

Note

nvs will attempt to install the version specified if it's not installed and switch to it later.

nvs use stable
nvs use nightly
nvs use v0.10.3
nvs use 0.10.3
nvs use 2db1ae3

Warning

If you're using windows, I think you will need administrator privilege terminal for nvs to symlink.

current

Display the currently active Neovim version.

nvs current

upgrade

Upgrade installed stable and/or nightly versions. If no argument is provided, both stable and nightly are upgraded (if installed).

Note

The upgrade command checks if the installed release is already up-to-date by comparing a stored identifier (release tag for stable, commit hash or published date for nightly). If no upgrade is needed, you'll be informed that you're on the latest version.

nvs upgrade         # Upgrades both stable and nightly if installed
nvs upgrade stable  # Upgrades only the stable release if installed
nvs upgrade nightly # Upgrades only the nightly release if installed

# or with shorthand
nvs up
nvs up stable
nvs up nightly

config

Switch between multiple configs. If no argument is provided, it will promp a select UI, else it will just open with specified name.

Note

nvs scans your configuration directory (e.g. ~/.config) for entries containing nvim in the name. Examples includes nvim, nvim-test, or nvim-vanilla.

nvs config
nvs config nvim-test

# or with shorthand
nvs c
nvs conf

uninstall

Uninstall an installed version. nvs will prompt a confirmation y/N if trying to uninstall the current used version and also prompt to select one of installed versions and switch to it.

nvs uninstall stable
nvs uninstall nightly
nvs uninstall v0.10.3
nvs uninstall 0.10.3
nvs uninstall 2db1ae3

# or with shorthand
nvs rm stable
nvs remove nightly
nvs un 0.10.3

path

Best effort to automatically add the global binary directory to your PATH.

nvs path

Note

This won't work if you're managing your system with nix home manager. See details below how to configure it

env

Prints the env configuration used by NVS (NVS_CONFIG_DIR, NVS_CACHE_DIR, and NVS_BIN_DIR).

nvs env

reset

Reset to factory state.

Warning

This command will delete all data in your configuration and cache directories—determined based on OS conventions or the environment variables (NVS_CONFIG_DIR and NVS_CACHE_DIR)—and remove the nvim binary from your binary directory (or NVS_BIN_DIR). Use with caution.

nvs reset

🔗 Adding nvs to Your PATH

To easily run the Neovim binary provided by nvs, you need to add the global binary directory to your PATH. By default, this is set according to OS best practices and environment variables. On Unix-like systems, the default is:

• Configuration Directory: ~/.config/nvs (or overridden via NVS_CONFIG_DIR)
• Cache Directory: ~/.cache/nvs (or overridden via NVS_CACHE_DIR)
• Global Binary Directory: ~/.local/bin (or overridden via NVS_BIN_DIR)

Note

We have provided nvs path command for the best effort to automatically setup the path for you in common shells. If it does not work, you need to set it up manually. See below with some example.

Macos Or Linux

Bash

Add the following line to your ~/.bashrc (or ~/.bash_profile on macOS):

export PATH="$HOME/.local/bin:$PATH"

Then, reload your configuration:

source ~/.bashrc   # or source ~/.bash_profile

Zsh

Add the following line to your ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

Then, reload your configuration:

source ~/.zshrc

Fish

Add the following line to your ~/.config/fish/config.fish:

set -gx PATH $HOME/.local/bin $PATH

Then, reload your configuration:

source ~/.config/fish/config.fish

Windows

Open an elevated Command Prompt (Run as administrator) and type:

setx PATH "%PATH%;%APPDATA%\nvs\bin"

Restart your Command Prompt (or log off and back on) for the changes to take effect.

Note

If you have overridden the default binary directory with the NVS_BIN_DIR environment variable, make sure to replace %APPDATA%\nvs\bin with your custom path in the above command.

Nix Home Manager

If you're using home manager with nix, you can try the following as documented at Nix Home Manager Docs :

{
 home.sessionPath = [
  "$HOME/.local/bin"
 ];
}

🧩 Shell Completions

nvs supports generating shell completions using Cobra’s built‐in functionality. You can easily enable command completions for your favorite shell by following the instructions below.

Generate the autocompletion script for nvs for the specified shell.
See each sub-command's help for details on how to use the generated script.

Usage:
  nvs completion [command]

Available Commands:
  bash        Generate the autocompletion script for bash
  fish        Generate the autocompletion script for fish
  powershell  Generate the autocompletion script for powershell
  zsh         Generate the autocompletion script for zsh

Bash

To enable Bash completions, add the following line to your ~/.bashrc (or ~/.bash_profile on macOS):

source <(nvs completion bash)

Then, reload your configuration:

source ~/.bashrc   # or source ~/.bash_profile

Zsh

For Zsh users, first ensure that completion is enabled by adding the following to your ~/.zshrc (if not already present):

autoload -U compinit && compinit

Then add the following line to generate and load nvs completions:

source <(nvs completion zsh)

Then, reload your configuration:

source ~/.zshrc

Fish

Fish shell users can generate completions with:

nvs completion fish | source

To make the completions permanent, save them to your completions directory:

nvs completion fish > ~/.config/fish/completions/nvs.fish

Then, reload your configuration:

source ~/.config/fish/config.fish

🤝 Contributing

Contributions are always welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to your branch
5. Open a pull request

📄 License

This project is licensed under the MIT License. Feel free to use, modify, and distribute it as you see fit.

Enjoy using nvs, and may your Neovim sessions be ever lit! ✨