ZVM(1)

💅 ZVM — like, the manual but make it make sense

ok so bestie. this is zvm(1), a User Command, and honestly? it's the main character of your Zig toolchain. buckle up 🎀

---

✨ NAME ✨

zvm — manage installed Zig and ZLS versions. that's it. that's the whole vibe. you install Zig versions, you pick which one you're using, you yeet the ones you don't want. slay.

---

🌸 SYNOPSIS 🌸

zvm [global-options] command [command-options]

like, options first, then a command, then that command's own options. easy. iykyk.

---

🦋 DESCRIPTION 🦋

okay so here's the tea ☕ — zvm downloads, installs, selects, and removes Zig compiler versions. and it does not stop there, bestie, because it can also:

• install a compatible ZLS release ✨
• run an installed Zig version without selecting it globally (casual. noncommittal. we love that)
• give each shell its own version (every terminal gets to be its own person 💅)
• deduplicate installations
• use alternative version maps or mirrors

Zig installations and ZVM state live under ~/.zvm by default. want a different home base? set ZVM_PATH to use another base directory. simple as.

---

👑 GLOBAL OPTIONS 👑

• --color mode — sets colored output, obviously, we are not living in a greyscale world. mode may be on, yes, y, enabled, true, off, no, n, disabled, or false. any other value — including the default toggle — toggles the saved setting. heads up though: this option requires a value when specified. no vibes-only invocation, she needs an argument 🙈
• -h, --help — show help. when you're lost, she's there 🫶
• -v, --version — print the ZVM version and the target platform. two for one, iconic.

---

🔥 COMMANDS 🔥

so many commands and every single one of them ate. here we go:

• install, i — download and install a Zig version, optionally with ZLS. see zvm-install(1).
• use — select an installed Zig version. see zvm-use(1).
• env — print shell code that gives the current shell its own Zig version, optionally switching automatically when you change directories. see zvm-env(1).
• run — run Zig from an installed version or from the project's minimum Zig version. see zvm-run(1).
• list-remote, ls-remote — list Zig versions available from the configured version map. see zvm-list-remote(1).
• list, ls — list installed Zig versions. see zvm-list(1).
• alias, kv — create, inspect, or remove names for installed Zig versions. see zvm-alias(1).
• uninstall, rm — remove an installed Zig version. say bye bestie 😭 see zvm-uninstall(1).
• clean — remove downloaded build archives and unreferenced dedupe-store files. see zvm-clean(1).
• dedupe — hard-link files that are identical across installed Zig versions. efficiency queen 💅 see zvm-dedupe(1).
• upgrade — upgrade ZVM itself, but only when self-upgrades are enabled in the build. see zvm-upgrade(1).
• mirrorlist — select the mirror-list URL used for Zig downloads. see zvm-mirrorlist(1).
• settings — view, edit, or check settings.json, either interactively or with jq-style paths. see zvm-settings(1).
• bug — start a bug report with the current environment prefilled (king behavior, honestly). see zvm-bug(1).
• version — print the installed ZVM version. see zvm-version(1).
• vmu — configure Zig and ZLS version-map sources. see zvm-vmu(1).
• completion — generate a shell completion script. see zvm-completion(1).

---

🌈 VERSION ARGUMENTS 🌈

commands that accept a Zig version support exact releases such as 0.14.1, the development channel master, and development build identifiers.

release shorthand like 0.14 or .14 selects the newest matching patch release. the stable shorthand selects the newest stable release. ngl, that's convenient.

here's the nuance tho — 👀 selection and removal resolve shorthand against installed versions, while installation may resolve it against the remote version map. same shorthand, different lookup, don't get caught out.

also: user-defined aliases may be used anywhere version arguments are accepted 🎀

---

🧚 ENVIRONMENT 🧚

• ZVM_PATH — ZVM base directory. defaults to ~/.zvm.
• ZVM_MULTISHELL_PATH — set by zvm-env(1) to the current shell's per-shell link; while it is set, zvm-use(1) changes only this shell. your terminal, your rules.
• ZVM_MULTISHELL_DIR — directory for per-shell links. it must be an absolute path outside the ZVM base directory. defaults to $XDG_STATE_HOME/zvm/multishells or the user cache directory; see zvm-env(1).
• ZVM_INSTALL — directory containing the ZVM executable, for self-upgrades.
• ZVM_TARGET_OS — override the operating system selected for an installation download.
• ZVM_TARGET_ARCH — override the architecture selected for an installation download.
• ZVM_HTTP_TIMEOUT — HTTP timeout in seconds for installation requests.
• ZVM_SET_CU — if set, disable the automatic ZVM upgrade check. (a little peace and quiet 🫶)
• ZVM_DEBUG — if set, enable debug logging.
• ZVM_SKIP_TLS_VERIFY — if set, disable TLS certificate verification for downloads. the value no-warn also suppresses the warning.

⚠️ okay so real talk: ZVM_SKIP_TLS_VERIFY turns off TLS certificate verification for downloads. that is a genuinely not-great security situation and you should not be chilling with it on by default. use at your own risk, bestie. 🙈

• BROWSER — command used by zvm-bug(1) to open a report URL.

---

💖 FILES 💖

• ~/.zvm/settings.json — persistent ZVM settings.
• ~/.zvm/aliases.json — version aliases used by zvm-alias(1).
• ~/.zvm/bin/zig — link to the currently selected Zig executable on Unix-like systems.
• ~/.zvm/bin/zls — link to the selected ZLS executable, when installed.
• ~/.zvm/store/ — content-addressed hard links created by zvm-dedupe(1). never a Zig version. like, do not go poking around in there expecting a compiler, she's a storage girlie.

when ZVM_PATH is set, these paths are relative to that directory instead of ~/.zvm. 🎀

---

⭐ EXAMPLES ⭐

zvm install 0.14.1
zvm install --zls master
zvm use stable
zvm run 0.13 build test
zvm ls
zvm alias work 0.14.1

look at her go 😭✨

---

💀 BUGS 💀

report issues at https://github.com/tristanisham/zvm/issues/. please do, we want to know.

---

🌸 AUTHOR 🌸

Tristan Isham and ZVM contributors. legends, all of them 👑

---

🎀 SEE ALSO 🎀

zig(1), zvm-install(1), zvm-use(1), zvm-run(1), zvm-list(1), zvm-alias(1)

---

okay that's the whole page, you're officially educated 💜 this was ZVM v0.9.4, dated August 2026 — go forth and manage those Zig versions, bestie. periodt. 🦋