⚡ Zig Version Manager (`zvm`)

⚡ Fast and simple zig version manager

zvm is a blazingly fast and intuitive command-line version manager for the Zig programming language. Effortlessly install, manage, and switch between multiple Zig versions with automatic project-based version detection.

📦 Installation

macOS/Linux (Homebrew)

brew tap hendriknielaender/zvm
brew install zvm

Pre-built binaries for Windows, MacOS, and Linux are available for each release.

Quick Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/hendriknielaender/zvm/main/install.sh | bash

Install specific version or rollback:

# Install specific version
curl -fsSL https://raw.githubusercontent.com/hendriknielaender/zvm/main/install.sh | bash -s "v0.15.0"

# Rollback to previous version
curl -fsSL https://raw.githubusercontent.com/hendriknielaender/zvm/main/install.sh | bash -s "v0.14.0"

# Also works with 'zvm-' prefix
curl -fsSL https://raw.githubusercontent.com/hendriknielaender/zvm/main/install.sh | bash -s "zvm-v0.15.0"

The installer will download the appropriate binary for your platform and install it to ~/.local/bin. Make sure this directory is in your PATH.

Windows (PowerShell)

irm https://raw.githubusercontent.com/hendriknielaender/zvm/master/install.ps1 | iex

Manual Installation

Download the latest binary from our releases page.

Setup Your Shell

After installation, configure your shell environment:

# Get shell-specific configuration
zvm env

# Example output:
# Add this to your ~/.bashrc, ~/.profile, or ~/.zshrc:
export PATH="/home/user/.local/share/zvm/bin:$PATH"

📖 Usage Guide

Core Commands

Command	Description	Example
`install`	Install a Zig version	`zvm install 0.13.0`
`use`	Switch to a version	`zvm use 0.13.0`
`list`	List installed versions	`zvm list --system`
`list-remote`	List available versions	`zvm list-remote`
`remove`	Remove a version	`zvm remove 0.12.0`
`clean`	Clean up cache	`zvm clean`

🎯 Auto-version detection

Automatically detects the required Zig version from your project's build.zig.zon file.

Create a build.zig.zon in your project root:

.{
    .name = "my-project",
    .version = "0.1.0",
    .minimum_zig_version = "0.13.0",
    .dependencies = .{},
}

Now simply run zig build or any Zig command - zvm will:

🔍 Detect the required version from build.zig.zon
📦 Automatically install it if not present
🎯 Use the correct version for your project

# zvm automatically detects and uses the right version
zig build
zig run src/main.zig
# Or specify version explicitly
zig 0.13.0 build

Installation Examples

# Install latest stable Zig
zvm install 0.13.0

# Install with debug output
zvm install 0.13.0 --debug

# Install master/development build
zvm install master

# Install ZLS (Language Server)
zvm install zls 0.13.0

# Use specific mirror for downloads
zvm install 0.13.0 --mirror=0

Version Management

# Switch to specific version
zvm use 0.13.0

# List installed versions
zvm list --system

# List all available versions
zvm list-remote

# Remove old version
zvm remove 0.12.0

# Clean up download cache
zvm clean

Advanced Usage

# JSON output for automation
zvm --json list

# Quiet mode (errors only)
zvm --quiet install master

# Force colored output
zvm --color list

# List available download mirrors
zvm list-mirrors

🔧 Configuration

Global Options

Flag	Description
`--json`	Output in JSON format
`--quiet`, `-q`	Suppress non-error output
`--no-color`	Disable colored output
`--color`	Force colored output
`--help`, `-h`	Show help
`--version`	Show version

Environment Variables

Variable	Description	Default
`XDG_DATA_HOME`	Data directory location	`~/.local/share`
`ZVM_DEBUG`	Enable debug logging	`false`

🌟 Shell Completions

Enhance your CLI experience with tab completion!

Bash

# Generate and install completion
zvm completions bash > /etc/bash_completion.d/zvm
source ~/.bashrc

Zsh

# Generate completion script
zvm completions zsh > ~/.zsh/completions/_zvm

# Add to ~/.zshrc
fpath+=(~/.zsh/completions)
autoload -U compinit && compinit

Fish

# Generate completion for Fish
zvm completions fish > ~/.config/fish/completions/zvm.fish

🏗️ Building from Source

Prerequisites

Zig 0.15.1 or later

Build Steps

git clone https://github.com/hendriknielaender/zvm.git
cd zvm
zig build -Doptimize=ReleaseSafe

🐛 Troubleshooting

Common Issues

PATH not updated after installation

# Re-run shell configuration
zvm env
source ~/.bashrc  # or ~/.zshrc

Version detection not working

Ensure build.zig.zon contains minimum_zig_version field
Check file is in project root or parent directories

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/hendriknielaender/zvm.git
cd zvm
zig build test

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This project is not affiliated with the ZVM project maintained by @tristanisham. Both projects operate independently, and any similarities are coincidental.

README

⚡ Zig Version Manager (zvm)