Zig version manager for Linux and Windows
  • Zig 83%
  • PowerShell 9.5%
  • Shell 7.5%
Find a file
2026-08-09 13:08:39 +02:00
src test: add unit coverage for core behavior 2026-08-09 13:08:39 +02:00
.gitignore init 2026-07-21 04:12:13 +02:00
build.zig errors: use native error formatting 2026-07-29 22:49:49 +02:00
build.zig.zon release: bump version to 0.1.4 2026-08-07 00:36:51 +02:00
install.linux.sh installer: expose zvm in the current session 2026-08-04 17:44:31 +02:00
install.ps1 installer: fix sourced detection when piping through Bash 2026-08-07 00:36:45 +02:00
install.windows.ps1 installer: expose zvm in the current session 2026-08-04 17:44:31 +02:00
LICENSE init 2026-07-21 04:12:13 +02:00
README.md installer: add non-interactive path options 2026-08-04 15:03:37 +02:00

zvm

zvm is a small Zig version manager for Linux and Windows.

The main idea is simple: put zvm's zig shim on your PATH, then keep typing zig build (or any other zig command) like normal. When you're inside a project, it reads the project's build.zig.zon, finds the requested Zig version, downloads it if needed, and runs the real compiler for you.

No use command before every project. No remembering which compiler you had installed last week. Just zig.

It also includes a separate zvm command for the usual version-manager jobs: installing versions ahead of time, listing them, choosing a default, and removing old ones.

Why this exists

I liked the "look at build.zig.zon and get out of the way" workflow from anyzig. I also wanted a proper cache, normal management commands, fallback mirrors, and visible download progress.

So zvm is meant to be a fairly boring tool in the best way: it should pick the right compiler and let you get back to your project.

What it does

There are two executables:

  • zig is the transparent shim. This is the one you put on your PATH and use day to day.
  • zvm is the management CLI, not really required to be on PATH, but useful if you use it frequently.

When the shim needs to choose a version, it checks these in order:

  1. A version written directly after zig, for example zig 0.16.0 build.
  2. minimum_zig_version from the nearest build.zig.zon, searching upward from the current directory.
  3. Your configured default version.
  4. The version you used most recently.

minimum_zig_version is treated as an exact version here. That may sound a little strict, but it is the least surprising option for a compiler manager: the project asks for a version, and zvm uses that version.

Downloads and verification

zvm gets Zig's official community-mirror list, shuffles it, and tries mirrors before falling back to ziglang.org. If a mirror stops responding while zvm is waiting for response data, it gives up after 5 seconds and moves on.

Downloads listed in Zig's official index.json are verified with their SHA-256 checksum. For older development snapshots that are no longer listed there, zvm tries the adjacent Minisign signature instead. If neither one is available, an interactive install asks before continuing, a non-interactive install refuses the unverified compiler.

This mostly comes up with IDEs. If an IDE starts zig for a project whose required compiler is not installed and that compiler cannot be verified, there is no terminal available for zvm to ask you the question, so the IDE request fails. Open a terminal in that project and run zig once instead, zvm will resolve and install the required version there (asking if needed). After that, the IDE should find the cached compiler, restarting the IDE may be necessary.

There is also zvm --no-verify install <version> for situations where you really need to bypass verification.

Install

Linux:

curl -fsSL https://git.xeondev.com/nyan/zvm/raw/branch/main/install.ps1 | sh

Windows:

irm https://git.xeondev.com/nyan/zvm/raw/branch/main/install.ps1 | iex

Both commands use the same cross-platform installer. It installs zig and zvm into zvm's bin directory and offers to add that directory to your PATH.

For unattended installs, use -y / --yes to accept the normal defaults, or choose PATH setup explicitly with --add-to-path or --no-add-to-path. On Windows, the equivalent PowerShell parameters are -Yes (or -y), -AddToPath, and -NoAddToPath.

If zvm is already on your PATH and matches the latest release, the installer does nothing. To reinstall it anyway, use ./install.ps1 --force on Linux or .\install.ps1 -Force on Windows from a local checkout.

If you would rather build from a checkout:

Linux:

./install.ps1 --build

Windows:

.\install.ps1 -Build

Building from source needs the exact Zig version pinned in build.zig.zon.

Everyday usage

# In a project with minimum_zig_version in build.zig.zon
zig build

# Use a version for this one command only
zig 0.16.0 build-exe hello.zig

# Install something ahead of time
zvm install 0.15.0

# See what you have
zvm list

# See versions known by the official index
zvm list-remote

# Show the zvm version
zvm version

# See what `zig` would choose here, and why
zvm which

# Set or clear a fallback
zvm default 0.16.0
zvm default clear

# Clean up an old version
zvm remove 0.15.0

For extra diagnostics:

zvm --verbose install 0.16.0
# Linux
ZVM_DEBUG=1 zig build
# Windows PowerShell
$env:ZVM_DEBUG=1; zig build; Remove-Item Env:ZVM_DEBUG

The shim does not accept --verbose itself because all of its arguments need to be passed through untouched to the Zig compiler.

Where it stores things

zvm uses $ZVM_HOME when it is set. Otherwise it uses:

  • Windows: %LOCALAPPDATA%\zvm
  • Linux: $XDG_DATA_HOME/zvm, or ~/.local/share/zvm

Inside that directory you will find:

versions/       installed Zig toolchains
cache/          downloaded index and mirror metadata + temporary files
config.json     default and most recently used versions
bin/            the zvm `zig` shim and `zvm` CLI

An installed version is only moved into versions/ after extraction finishes, so an interrupted download should not leave behind a version that looks valid but is incomplete.

Supported platforms

zvm supports Linux and Windows on x86_64 and aarch64.

macOS is intentionally not listed yet. It might be possible to make it work, but shipping a platform I cannot properly test would be a bad deal for anyone who tries it, but contributions are welcomed ^^.

License

MIT. See LICENSE.