Zig version manager for Linux and Windows
  • Zig 86.4%
  • PowerShell 7.6%
  • Shell 6%
Find a file
2026-10-03 00:37:15 +02:00
src fix(net): transfer response buffer ownership 2026-10-03 00:31:08 +02:00
.gitignore init 2026-07-21 04:12:13 +02:00
build.zig build: omit unsupported ZLS shim from FreeBSD packages 2026-09-09 20:23:37 +02:00
build.zig.zon release: bump version to 0.2.1 2026-10-03 00:37:15 +02:00
install.posix.sh build: omit unsupported ZLS shim from FreeBSD packages 2026-09-09 20:23:37 +02:00
install.ps1 platform: add macOS and FreeBSD support 2026-08-18 17:32:36 +02:00
install.windows.ps1 zls: add --with-zls option to zvm install 2026-08-27 12:34:08 +02:00
LICENSE init 2026-07-21 04:12:13 +02:00
README.md build: omit unsupported ZLS shim from FreeBSD packages 2026-09-09 20:23:37 +02:00

zvm

zvm is a small Zig version manager for Linux, macOS, FreeBSD, 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 up to three executables:

  • zig is the transparent shim. This is the one you put on your PATH and use day to day.
  • zls does the same for the Zig language server on platforms with managed ZLS support: it picks the ZLS build compatible with the project's Zig version, installs it if needed, and runs it. Your editor just needs it on PATH.
  • zvm is the management CLI, not really required to be on PATH, but useful if you use it frequently.

ZLS is available when the ZLS project publishes a prebuilt artifact for your platform. zvm itself still supports FreeBSD, but managed ZLS currently does not have an official FreeBSD build, so the FreeBSD package does not install a zls shim that would hide an existing system ZLS.

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.

When ZLS is requested, zvm verifies its release with the checksum supplied by the ZLS release service. If a checksum is unavailable, it falls back to the adjacent official Minisign signature; it refuses to install a ZLS release that cannot be verified unless --no-verify is used.

Install

Linux, macOS, and FreeBSD:

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. On Linux, macOS, and Windows it installs the zig and zls shims plus the zvm CLI into zvm's bin directory. On FreeBSD it installs only zig and zvm, leaving any system-provided zls available. The installer 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 a POSIX system or .\install.ps1 -Force on Windows from a local checkout.

If you would rather build from a checkout:

Linux, macOS, and FreeBSD:

./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

# Install a version together with its matching ZLS (language server)
zvm install 0.16.0 --with-zls

# Run the language server for the project's Zig version (usually your editor does this)
zls

# 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

POSIX shells

ZVM_DEBUG=1 zig build

Windows PowerShell:

$env:ZVM_DEBUG=1; zig build; Remove-Item Env:ZVM_DEBUG

The shims do not accept --verbose because all of their arguments need to be passed through untouched to the tool.

Where it stores things

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

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

Inside that directory you will find:

versions/            installed Zig toolchains
versions/<v>/zls/    matching ZLS, when installed with --with-zls
cache/               downloaded index and mirror metadata + temporary files
config.json          default and most recently used versions
bin/                 zvm's `zig` and, where supported, `zls` shims plus the `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, macOS, FreeBSD, and Windows on x86_64 and aarch64. Managed ZLS downloads are currently available for Linux, macOS, and Windows; FreeBSD ZLS support will be enabled when an official prebuilt is published.

License

MIT. See LICENSE.