nvs

Neovim Version Switcher – Install, switch, and manage multiple Neovim versions with ease 🚀

---

Why nvs?

Managing multiple Neovim versions shouldn't be complicated. nvs makes it simple:

• ⚡ Instant Switching – Switch between versions in milliseconds
• 📌 Per-Project Versions – Pin versions with .nvs-version files
• 🔄 Auto-Switch – Automatically switch versions when changing directories
• 🌙 Nightly Support – First-class support for nightly builds with rollback capability
• 🔧 Build from Source – Install any commit directly from the Neovim repository
• 🔀 Config Switching – Toggle between multiple Neovim configurations
• 🩺 Self-Diagnosing – Built-in health checks with nvs doctor

$ nvs use stable
✓ Switched to Neovim stable

$ nvim -v
NVIM v0.10.4
Build type: Release
LuaJIT 2.1.1713484068

$ nvs use nightly
✓ Switched to Neovim nightly

$ nvim -v
NVIM v0.11.0-dev-1961+g7e2b75760f
Build type: RelWithDebInfo
LuaJIT 2.1.1741571767

---

Quick Start

1. Install nvs

macOS / Linux:

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

Windows (PowerShell):

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/y3owk1n/nvs/main/install.ps1" -OutFile "install.ps1"; .\install.ps1

Other methods: Homebrew · Nix · From Source

2. Set Up Your Shell

Add to your shell configuration (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish):

# Bash/Zsh
eval "$(nvs env --source)"

# Fish
nvs env --source | source

3. Install and Use Neovim

nvs install stable    # Install stable release
nvs use stable        # Switch to stable
nvim --version        # Verify installation

---

Command Reference

Command	Description
nvs install <version>	Install a Neovim version (stable, nightly, v0.10.3, commit hash)
nvs install --pick	Install with interactive version picker
nvs use <version>	Switch to an installed version
nvs use --pick	Switch with interactive version picker
nvs list	List installed versions
nvs list-remote	List available remote versions
nvs current	Show currently active version
nvs upgrade	Upgrade stable and/or nightly versions
nvs upgrade --pick	Upgrade with interactive version picker
nvs uninstall <version>	Remove an installed version
nvs uninstall --pick	Remove with interactive version picker
nvs pin [version]	Pin version to current directory (.nvs-version)
nvs pin --pick	Pin with interactive version picker
nvs rollback	Rollback to a previous nightly version
nvs run <version>	Run a version without switching
nvs run --pick	Run with interactive version picker
nvs config	Switch Neovim configuration
nvs doctor	Check system health
nvs hook <shell>	Generate shell hook for auto-switching

See the Usage Guide for detailed examples and options.

---

Features

Version Management

Install any Neovim version – stable releases, nightly builds, specific tags, or even build from any commit:

nvs install stable           # Latest stable
nvs install nightly          # Latest nightly
nvs install v0.10.3          # Specific version
nvs install 2db1ae3          # Build from commit

Per-Project Version Pinning

Pin a Neovim version to your project directory:

nvs pin stable               # Creates .nvs-version
nvs use                      # Reads from .nvs-version

Enable auto-switching to automatically switch versions when entering a directory:

# Add to shell config
eval "$(nvs hook bash)"      # or zsh/fish

Nightly Management

Keep multiple nightly versions and rollback when needed:

nvs upgrade nightly          # Upgrade to latest nightly
nvs rollback                 # List available rollback versions
nvs rollback 0               # Rollback to most recent previous

Configuration Switching

Manage multiple Neovim configurations:

nvs config                   # Interactive selection
nvs config nvim-test         # Direct switch

Scripting Support

All listing and status commands support --json for machine-readable output:

nvs list --json              # Installed versions as JSON
nvs current --json           # Current version details as JSON
nvs doctor --json            # System checks as JSON

---

System Requirements

Platform	Architecture	Status
macOS	Intel (amd64)	✅ Fully supported
macOS	Apple Silicon (arm64)	✅ Fully supported
Linux	amd64	✅ Fully supported
Linux	arm64	✅ Fully supported
Windows	amd64	✅ Fully supported
Windows	arm64	✅ Fully supported

Base dependencies: git, curl, tar Build dependencies: make, cmake, gettext, ninja (nvs checks for these automatically)

---

Documentation

Document	Description
Installation Guide	All installation methods and troubleshooting
Usage Guide	Complete command reference with examples
Configuration	Environment setup and customization
Development	Architecture and development setup
Contributing	How to contribute to nvs

---

Contributing

Contributions are welcome! See the Contributing Guide to get started.

git clone https://github.com/y3owk1n/nvs.git
cd nvs
just test    # Run tests
just lint    # Run linter
just build   # Build binary

---

License

MIT License © Kyle Wong