Skip to content
Back to search

zvm

MarketplaceWorks with Claude CodeGitHub

Zig Version Manager plugin for Claude Code

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tristanisham/zvm with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tristanisham/zvm'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tristanisham--zvm/badge.svg)](/listings/tristanisham--zvm)

HTML

<a href="/listings/tristanisham--zvm"><img src="/api/listings/tristanisham--zvm/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

ZVM lives entirely in `$HOME/.zvm` on all platforms it supports. Inside of the directory, ZVM will download new Zig versions and symlink whichever version you specify with `zvm use` to `$HOME/.zvm/bin`. You should add this folder to your path. After ZVM 0.2.3, ZVM's installer will now add ZVM to `$HOME/.zvm/self`. You should also add this directory as the environment variable `ZVM_INSTALL`. The installer scripts should handle this for you automatically on *nix and Windows systems.

If you don't want to use `ZVM_INSTALL` (like you already have ZVM in a place you like), then ZVM will update the exact executable you've called `upgrade` from.

All installation scripts hosted on `www.zvm.app` are identical to, and are automatically synced with their respective copies on GitHub.

www.zvm.app/install.sh === ./install.sh

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 27 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "zvm",
  3. "description": "Zig Version Manager plugin for Claude Code",
  4. "owner": {
  5. "name": "Tristan Isham"
  6. },
  7. "plugins": [
  8. {
  9. "name": "zvm",
  10. "description": "Install, pin, and switch Zig toolchains with zvm (Zig Version Manager).",
  11. "version": "0.9.5",
  12. "source": "./",
  13. "author": {
  14. "name": "Tristan Isham"
  15. },
  16. "homepage": "https://www.zvm.app",
  17. "license": "MIT",
  18. "keywords": [
  19. "zig",
  20. "zvm",
  21. "version-manager",
  22. "toolchain",
  23. "zls"
  24. ]
  25. }
  26. ]
  27. }
README.md · README · 1,062 lines · 3 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/logo.png" alt="ZVM orange planet logo" width="400" height="400" />
  3. </p>
  4. Zig Version Manager (zvm) is a tool for managing your
  5. [Zig](https://ziglang.org/) installs. With std under heavy development and a
  6. large feature roadmap, Zig is bound to continue changing. Breaking existing
  7. builds, updating valid syntax, and introducing new features like a package
  8. manager. While this is great for developers, it also can lead to headaches when
  9. you need multiple versions of a language installed to compile your projects, or
  10. a language gets updated frequently.
  11. ## Donate
  12. - [Paypal](https://www.paypal.com/donate/?hosted_button_id=HFTFEFXP2A388)
  13. ## Join our Community
  14. - [Twitch](https://twitch.tv/atalocke)
  15. - [Twitter|X](https://twitter.com/atalocke)
  16. <a href="https://polar.sh/tristanisham"><picture><source media="(prefers-color-scheme: dark)" srcset="https://polar.sh/embed/subscribe.svg?org=tristanisham&label=Subscribe&darkmode"><img alt="Subscribe on Polar" src="https://polar.sh/embed/subscribe.svg?org=tristanisham&label=Subscribe"></picture></a>
  17. # Installing ZVM
  18. ZVM lives entirely in `$HOME/.zvm` on all platforms it supports. Inside of the
  19. directory, ZVM will download new Zig versions and symlink whichever version you
  20. specify with `zvm use` to `$HOME/.zvm/bin`. You should add this folder to your
  21. path. After ZVM 0.2.3, ZVM's installer will now add ZVM to `$HOME/.zvm/self`.
  22. You should also add this directory as the environment variable `ZVM_INSTALL`.
  23. The installer scripts should handle this for you automatically on *nix and
  24. Windows systems.
  25. If you don't want to use `ZVM_INSTALL` (like you already have ZVM in a place you
  26. like), then ZVM will update the exact executable you've called `upgrade` from.
  27. All installation scripts hosted on `www.zvm.app` are identical to, and are
  28. automatically synced with their respective copies on GitHub.
  29. ```
  30. www.zvm.app/install.sh === ./install.sh
  31. ```
  32. # Linux, BSD, MacOS, *nix
  33. ```sh
  34. curl https://www.zvm.app/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 47 on GitHub
  35. ```
  36. <!-- This script will **automatically append** ZVM's required environment variables (see below) to `~/.profile` or `~/.bashrc`. -->
  37. <!-- If these files don't exist, append the following to your shell's startup script.
  38. ```sh
  39. echo "# ZVM" >> $HOME/.profile
  40. echo export ZVM_INSTALL="$HOME/.zvm/self" >> $HOME/.profile
  41. echo export PATH="$PATH:$HOME/.zvm/bin" >> $HOME/.profile
  42. echo export PATH="$PATH:$ZVM_INSTALL/" >> $HOME/.profile
  43. ``` -->
  44. # Windows
  45. ## PowerShell
  46. ```ps1
  47. irm "https://www.zvm.app/install.ps1" | iex
  48. ```
  49. ## Command Prompt
  50. ```cmd
  51. powershell -c "irm https://www.zvm.app/install.ps1 | iex"
  52. ```
  53. # You Have Go Installed
  54. ```sh
  55. go install -ldflags "-s -w" github.com/tristanisham/zvm@latest
  56. ```
  57. ## Manually
  58. Please grab the
  59. [latest release](https://github.com/tristanisham/zvm/releases/latest).
  60. ### Verifying a download
  61. Releases are built by GitHub Actions, which publishes a `SHA256SUMS` file and a
  62. signed [build provenance attestation](https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations)
  63. for every archive. To check that an archive is exactly what CI built from this
  64. repository:
  65. ```bash
  66. gh attestation verify zvm-linux-amd64.tar --repo tristanisham/zvm
  67. # or, without the GitHub CLI, just the checksum:
  68. sha256sum --check --ignore-missing SHA256SUMS
  69. ```
  70. This covers releases built by the workflow, starting after v0.9.3. The install
  71. scripts and `zvm upgrade` don't check it yet.
  72. Alternatively, you can build the app by cloning the repository and running
  73. ```bash
  74. go build .
  75. ./zvm
  76. ```
  77. If you want to disable that ZVM can automatically update itself, you can run
  78. ```bash
  79. go build -tags noAutoUpgrades .
  80. ```
  81. instead for building the app.
  82. ## Putting ZVM on your Path
  83. ZVM requires a few directories to be on your `$PATH`.
  84. ### Linux, BSD, MacOS, *nix
  85. The installer script handles this for you automatically. If you need to set it
  86. up manually, append the following to your shell's startup file (`~/.bashrc`,
  87. `~/.zshrc`, or `~/.profile`):
  88. ```sh
  89. export ZVM_INSTALL="$HOME/.zvm/self"
  90. export PATH="$HOME/.zvm/bin:$ZVM_INSTALL:$PATH"
  91. ```
  92. Then restart your shell or `source` the file for the changes to take effect.
  93. ### Windows
  94. If you don't know how to update your environment variables permanently on
  95. Windows, you can follow
  96. [this guide](https://www.computerhope.com/issues/ch000549.htm). Once you're in
  97. the appropriate menu, add or append to the following environment variables:
  98. Add
  99. - ZVM_INSTALL: `%USERPROFILE%\.zvm\self`
  100. Append
  101. - PATH: `%USERPROFILE%\.zvm\bin`
  102. - PATH: `%ZVM_INSTALL%`
  103. ## Configure ZVM path
  104. It is possible to overwrite the default behavior of ZVM to adhere to XDG
  105. specification on Linux. There's an environment variable `ZVM_PATH`. Setting it
  106. to `$XDG_DATA_HOME/zvm` will do the trick.
  107. ## Community Package
  108. ### AUR
  109. `zvm` on the [Arch AUR](https://aur.archlinux.org/packages/zvm) is a
  110. community-maintained package, and may be out of date.
  111. # Why should I use ZVM?
  112. While Zig is still pre-1.0 if you're going to stay up-to-date with the master
  113. branch, you're going to be downloading Zig quite often. You could do it
  114. manually, having to scroll around to find your appropriate version, decompress
  115. it, and install it on your `$PATH`. Or, you could install ZVM and run
  116. `zvm i master` every time you want to update. `zvm` is a static binary under a
  117. permissive license. It supports more platforms than any other Zig version
  118. manager. ZVM has no system dependencies. Whether you're on
  119. Windows, MacOS, Linux, a flavor of BSD, or Plan 9 `zvm` will let you install,
  120. switch between, and run multiple versions of Zig.
  121. # Using ZVM with AI coding agents
  122. ZVM ships one portable agent skill with plugin manifests for Claude Code and
  123. Codex. It teaches coding agents to reach for `zvm` instead of a distro package
  124. or a hand-unpacked tarball, and to drive it correctly when they do.
  125. ### Claude Code
  126. ```
  127. /plugin marketplace add tristanisham/zvm
  128. /plugin install zvm
  129. ```
  130. The same commands are also available from a shell:
  131. ```sh
  132. claude plugin marketplace add tristanisham/zvm
  133. claude plugin install zvm@zvm
  134. ```
  135. Print the bundled skill and command reference as Markdown with `zvm --skill`:
  136. ```sh
  137. zvm --skill > zig-versions.md
  138. ```
  139. ### Codex and other agents
  140. The repository includes a Codex plugin manifest at `.codex-plugin/plugin.json`.
  141. The underlying `skills/zig-versions/` directory uses the portable Agent Skills
  142. layout, so other skill-compatible agents can load that directory directly.
  143. The shared skill covers ZVM's real command surface, how to find the version a
  144. repository actually wants (`//! zvm-lock:` in `build.zig`,
  145. `.minimum_zig_version` in `build.zig.zon`), and why agents should prefer
  146. `zvm run` over `zvm use` so they never repoint your global Zig without being
  147. asked. The command reference is generated from ZVM's own CLI definition, so it
  148. cannot drift from the binary.
  149. # Contributing and Notice
  150. `zvm` is stable software. Pre-v1.0.0 any breaking changes will be clearly
  151. labeled, and any commands potentially on the chopping block will print notice.
  152. The program is under constant development, and the author is very willing to
  153. work with contributors. **If you have any issues, ideas, or contributions you'd
  154. like to suggest
  155. [create a GitHub issue](https://github.com/tristanisham/zvm/issues/new/choose)**.
  156. # How to use ZVM
  157. ## Install
  158. ```sh
  159. zvm install <version>
  160. # Or
  161. zvm i <version>
  162. ```
  163. Use `install` or `i` to download a specific version of Zig. You can pass an
  164. exact version, a [shorthand](#version-shorthand), or an
  165. [alias](#version-aliases).
  166. ```sh
  167. zvm i 0.13.0 # Install an exact version
  168. zvm i master # Install the current master nightly
  169. zvm i stable # Install the latest stable release
  170. zvm i .14 # Shorthand — installs 0.14.x (latest patch)
  171. ```
  172. ### Download checks
  173. ZVM checks official Zig downloads against Zig's signing key, including the
  174. filename in the signature. If a mirror serves the wrong file, or a download
  175. fails verification, ZVM tries the next mirror. The original download URL is
  176. the last fallback.
  177. After a verified download, ZVM records the archive's SHA-256 in
  178. `~/.zvm/known_hashes.json`. If that same filename ever comes back with a
  179. different hash, the install fails. `--force` still reinstalls an existing
  180. version, but it doesn't bypass this check. Custom version maps keep using
  181. their published checksums and aren't added to this store.
  182. ### Version Shorthand
  183. You can use abbreviated version numbers and ZVM will resolve them to the
  184. **latest matching release**:
  185. ```sh
  186. zvm i 0.13 # Installs 0.13.0
  187. zvm i .13 # Same as above — a leading dot implies "0."
  188. zvm i 0.15 # Installs 0.15.2 (latest 0.15.x patch)
  189. zvm i .15 # Same — resolves to 0.15.2
  190. ```
  191. Whenever ZVM expands a shorthand, it prints the result so you know exactly
  192. what's being fetched:
  193. ```
  194. $ zvm i .14
  195. Resolved ".14" to 0.14.1
  196. ...
  197. ```
  198. Shorthand works across every command that takes a version:
  199. ```sh
  200. zvm i 0.14 # install
  201. zvm use .13 # switch active version
  202. zvm run 0.12 version
  203. zvm rm .11 # uninstall
  204. ```
  205. For `use` and `rm`, shorthand is resolved against your **locally installed**
  206. versions. For `install` and `run`, it resolves against the **remote** version
  207. map.
  208. ### Version Aliases
  209. ZVM understands a few named aliases in addition to concrete versions:
  210. | Alias | Resolves to |
  211. | -------- | -------------------------------------------------------- |
  212. | `master` | The current `master` nightly build (passes through as-is) |
  213. | `stable` | The highest non-dev, non-master release (e.g. `0.16.0`) |
  214. ```sh
  215. zvm i stable # Install the latest stable release
  216. zvm use stable # Switch to the latest installed stable release
  217. zvm i master # Install the current master nightly
  218. ```
  219. `stable` is especially useful in automation — you don't have to know the exact
  220. version number to grab the newest release.
  221. You can also create your own named aliases with the [`alias` command](#alias-your-zig-versions).
  222. ### Force Install
  223. As of `v0.7.6` ZVM will now skip downloading a version if it is already
  224. installed. You can always force an install with the `--force` or `-f` flag.
  225. ```sh
  226. zvm i --force master
  227. ```
  228. You can also enable the old behavior by setting the new `alwaysForceInstall`
  229. field to `true` in `~/.zvm/settings.json`.
  230. ### Install Without Switching
  231. By default, installing Zig also makes that version active. Pass `--skip-use`
  232. or `-k` to install it without changing the active Zig version:
  233. ```sh
  234. zvm i --skip-use 0.15.2
  235. ```
  236. This also applies when installing ZLS with `--zls`.
  237. ### Keep the Old Master Build
  238. Installing `master` replaces the master build you already have. Pass `--keep-and-rename <name>` (or `--keep <name>` or `-n <name>`) to keep the old build instead: ZVM moves it to a directory named after its version and saves `<name>` as an [alias](#alias-your-zig-versions) for it.
  239. ```sh
  240. zvm i --keep before-upgrade master
  241. zvm use before-upgrade
  242. ```
  243. The flag is ignored for other versions, and when there is no old build to keep. If `<name>` is already an alias, ZVM asks before pointing it at the old build; answering no, or running without input, stops the install without replacing `master`. If the old version’s destination already exists, the command also stops without replacing `master`.
  244. ### Install a Specific Development Build
  245. Zig development builds can be installed by their full build identifier, such as
  246. `0.16.0-dev.1334+06d08daba`. ZVM downloads these builds directly from
  247. `ziglang.org/builds` because they are not listed in the release version map.
  248. Development builds do not have a version-map SHA-256 checksum. ZVM warns about
  249. this and asks for confirmation before continuing:
  250. ```sh
  251. zvm i 0.16.0-dev.1334+06d08daba
  252. ```
  253. For an explicit non-interactive install, pass `--skip-shasum` (or `-s`). This
  254. also skips SHA-256 verification for regular Zig and ZLS installations, so use
  255. it only when you accept that risk:
  256. ```sh
  257. zvm i --skip-shasum 0.16.0-dev.1334+06d08daba
  258. ```
  259. ### Customize HTTP Timeout
  260. Set the HTTP timeout in seconds for version metadata and installation downloads with `ZVM_HTTP_TIMEOUT`. For `zvm i`, you can also use the `--http.timeout` flag. The default is 180 seconds; `0` disables the timeout.
  261. ```sh
  262. zvm i --http.timeout 30
  263. ```
  264. ### Install ZLS with ZVM
  265. You can now install ZLS with your Zig download! To install ZLS with ZVM, simply
  266. pass the `--zls` flag with `zvm i`. For example:
  267. ```sh
  268. zvm i --zls master
  269. ```
  270. By default, ZVM stops if the Zig installation fails and does not attempt the
  271. requested ZLS installation. To attempt ZLS even after a Zig installation error,
  272. set `alwaysInstallZLS` to `true` in `~/.zvm/settings.json`:
  273. ```json
  274. {
  275. "alwaysInstallZLS": true
  276. }
  277. ```
  278. The command still returns the Zig installation error. If ZLS also fails, ZVM
  279. returns both errors.
  280. ### Install for a Different Target Platform
  281. If you're on a platform where pre-built Zig binaries aren't available for a
  282. specific version (e.g., FreeBSD for Zig 0.14.x), you can override the target
  283. OS and/or architecture to download a compatible build.
  284. Use the `--target-os` and `--target-arch` flags (also available as
  285. `--target.os` and `--target.arch`):
  286. ```sh
  287. zvm i --target-os linux --target-arch x86_64 0.14.0
  288. ```
  289. Or set the `ZVM_TARGET_OS` and `ZVM_TARGET_ARCH` environment variables:
  290. ```sh
  291. export ZVM_TARGET_OS=linux
  292. export ZVM_TARGET_ARCH=x86_64
  293. zvm i 0.14.0
  294. ```
  295. Both Go-style names (e.g., `darwin`, `amd64`) and Zig-style names (e.g.,
  296. `macos`, `x86_64`) are accepted.
  297. #### Select ZLS compatibility mode
  298. By default, ZVM will install a ZLS build, which can be used with the given Zig
  299. version, but may not be able to build ZLS from source. If you want to use a ZLS
  300. build, which can be built using the selected Zig version, pass the `--full` flag
  301. with `zvm i --zls`. For example:
  302. ```sh
  303. zvm i --zls --full master
  304. ```
  305. > [!IMPORTANT]
  306. > This does not apply to tagged releases, e.g.: `0.13.0`
  307. ## Switch between installed Zig versions
  308. ```sh
  309. zvm use <version>
  310. ```
  311. Use `use` to switch between versions of Zig. The version argument accepts
  312. [shorthand](#version-shorthand) and [aliases](#version-aliases).
  313. ```sh
  314. zvm use master # Switch to master
  315. zvm use stable # Switch to the latest installed stable release
  316. zvm use 0.13 # Resolves to 0.13.x (latest installed patch)
  317. zvm use .14 # Same — leading dot implies "0."
  318. ```
  319. To use a Zig you built yourself, link it into `~/.zvm` under any name. ZVM
  320. treats the link like an installed version once the directory it points to
  321. holds a `zig` executable:
  322. ```sh
  323. ln -s ~/src/zig/zig-out/bin ~/.zvm/local # the directory that contains `zig`
  324. zvm use local
  325. zvm run local version
  326. ```
  327. `zvm uninstall` won't remove a linked build, and `zvm dedupe` leaves its files
  328. alone. Delete the link yourself when you're done with it.
  329. ### Give each shell its own Zig version
  330. By default, `zvm use` switches Zig for every terminal at once. If you'd rather
  331. each shell keep its own version, add the line for your shell to its startup
  332. file:
  333. ```sh
  334. eval "$(zvm env --shell bash --use-on-cd)" # ~/.bashrc
  335. eval "$(zvm env --shell zsh --use-on-cd)" # ~/.zshrc
  336. zvm env --shell fish --use-on-cd | source # ~/.config/fish/config.fish
  337. zvm env --shell powershell --use-on-cd | Out-String | Invoke-Expression # $PROFILE
  338. ```
  339. Now `zvm use` only changes the shell you ran it in. New shells start on your
  340. global version, which you can still change with `--global`.
  341. ```sh
  342. zvm use 0.15.2 # This shell only
  343. zvm use --global 0.15.2 # The default for new shells
  344. ```
  345. You can also run `zvm env --shell bash` without `--use-on-cd` if you only
  346. want per-shell versions. `env` prints the setup code; evaluating it in your
  347. shell is what updates that shell's environment. `zvm run <version> ...`
  348. still runs one command without switching either default.
  349. `--use-on-cd` switches versions for you when you `cd` into a project. ZVM looks
  350. in the current directory and its parents for a `//! zvm-lock: <version>` line in
  351. `build.zig`, then `.minimum_zig_version` in `build.zig.zon`. If that version
  352. isn't installed, ZVM tells you how to install it instead of prompting. Leaving
  353. the project keeps you on its version.
  354. Under the hood, `zvm env` makes a link for the shell (in your user cache
  355. directory, or `$ZVM_MULTISHELL_DIR`), exports it as `ZVM_MULTISHELL_PATH`, and
  356. puts it in front of `~/.zvm/bin` on your `PATH`. `zvm clean` removes links left
  357. behind by shells that have exited.
  358. > [!NOTE]
  359. > There are two things to know:
  360. >
  361. > - Programs started from a shell inherit `ZVM_MULTISHELL_PATH`. If a script or
  362. > editor launched from that shell runs `zvm use`, it switches **that shell's**
  363. > version, not the global one. Use `zvm use --global` in scripts that should
  364. > change the default.
  365. > - bash has no `cd` hook, so ZVM switches just before the next prompt. That
  366. > means `cd my-project && zig build` on one line still builds with the old
  367. > version. zsh, fish, and PowerShell switch on the `cd` itself.
  368. ## Alias your Zig versions
  369. Use `alias` (or `kv`) to give an installed Zig version a custom name. The version must already be installed, and shorthand is supported.
  370. ```sh
  371. zvm alias work 0.13.0 # Point "work" at 0.13.0
  372. zvm alias play .14 # Resolve to the latest installed 0.14.x
  373. zvm use work # Switch versions by alias
  374. zvm run play version # Run a command with the aliased version
  375. ```
  376. Aliases work with `install`, `use`, `run`, and `rm`. Setting an existing name updates it.
  377. ```sh
  378. zvm alias # List all aliases
  379. zvm alias work # Print one alias
  380. zvm alias -d work # Delete one alias
  381. zvm alias --clear # Delete all aliases
  382. ```
  383. ## List installed Zig versions
  384. ```sh
  385. # Example
  386. zvm ls
  387. ```
  388. Use `ls` to list all installed version of Zig.
  389. ### List all versions of Zig available
  390. ```sh
  391. zvm ls --all
  392. ```
  393. The `--all` flag will list the available versions of Zig for download. Not the
  394. versions locally installed.
  395. ### List set version maps
  396. ```sh
  397. zvm ls --vmu
  398. ```
  399. The `--vmu` flag will list set version maps for Zig and ZLS downloads.
  400. ## Uninstall a Zig version
  401. ```sh
  402. zvm rm 0.10.0 # Remove an exact version
  403. zvm rm .13 # Shorthand — removes the installed 0.13.x
  404. zvm rm stable # Alias — removes the installed stable release
  405. ```
  406. Use `uninstall` or `rm` to remove an installed version from your system.
  407. The version argument accepts [shorthand](#version-shorthand) and
  408. [aliases](#version-aliases), resolved against what you have installed locally.
  409. ## Upgrade your ZVM installation
  410. As of `zvm v0.2.3` you can now upgrade your ZVM installation from, well, zvm.
  411. Just run:
  412. ```sh
  413. zvm upgrade
  414. ```
  415. The latest version of ZVM should install on your machine, regardless of where
  416. your binary lives (though if you have your binary in a privileged folder, you
  417. may have to run this command with `sudo`).
  418. ### Install via Package Manager
  419. ZVM (> v0.8.14) can also be built without its auto upgrader (`zvm upgrade`).
  420. This is to make installing ZVM via a package manager easier for those who prefer
  421. this method.
  422. When you run a build of ZVM with the autoupgrader disabled, you will see a
  423. builder-specified message when you run `zvm upgrade`.
  424. <img width="1041" height="73" alt="image" src="https://github.com/user-attachments/assets/4143436a-8838-438e-9e15-9aab63b378a3" />
  425. ```go
  426. go build -ldflags=-w -s -X 'main.BuildUpgradeMessage=Command to upgrade ZVM goes here.'
  427. ```
  428. Remember, ZVM is an open source project. Anyone can customize and distribute it.
  429. ## Clean up build artifacts
  430. ```sh
  431. # Example
  432. zvm clean
  433. ```
  434. Use `clean` to remove build artifacts (Good if you're on Windows). It also
  435. removes per-shell links left behind by `zvm env`, and files from the dedupe
  436. store (below) that no installed version links to any more.
  437. ## Deduplicate installed versions
  438. ```sh
  439. zvm dedupe # all installed versions
  440. zvm dedupe 0.15.1 0.15.2 # just these
  441. zvm dedupe --auto on # also dedupe every future `zvm install` (default: off)
  442. zvm dedupe --auto off # stop deduping future installs automatically
  443. ```
  444. Zig releases ship mostly the same files: `0.15.1` and `0.15.2` share all but
  445. ~50 of ~18,000 files. Deduping keeps one copy of the shared files; the space
  446. saved depends on the sizes of the files that differ. `zvm dedupe` hashes each file and
  447. replaces duplicates with hard links into `~/.zvm/store/`, the way pnpm and uv
  448. share packages. Files are only merged if content, permissions and owner match;
  449. symlinks are left alone. It is safe to re-run or interrupt, and files on a
  450. filesystem without hard links are simply skipped. `zvm uninstall` and
  451. `zvm clean` drop store files nothing links to any more.
  452. Hashing every file takes a while (around 20 seconds for four versions), so
  453. `zvm dedupe` shows a progress bar and ends by telling you how much space it
  454. reclaimed.
  455. `--auto` saves your preference and exits. Turning it on doesn't dedupe
  456. versions you've already installed, so run `zvm dedupe` once to include those.
  457. Turning it off doesn't make separate copies of files that are already shared.
  458. You can also read or change this preference with `zvm settings .autoDedupe`.
  459. Because deduped files are shared, **editing one in place (say, patching
  460. `lib/std` in one version) changes it in every version that shares it.** If you
  461. patch Zig's standard library, don't dedupe that version, or reinstall it with
  462. `zvm install --force` afterwards. Use `du -sh ~/.zvm` (one `du` over the whole
  463. tree) to see the real total: `du` counts each hard-linked file once per
  464. invocation, so summing separate `du` runs per version overstates usage.
  465. ## Run installed version of Zig without switching your default
  466. If you want to run a version of Zig without setting it as your default, the new
  467. `run` command is your friend. The version argument accepts
  468. [shorthand](#version-shorthand) and [aliases](#version-aliases).
  469. ```sh
  470. zig version
  471. # 0.13.0
  472. zvm run 0.11.0 version
  473. # 0.11.0
  474. zvm run .12 version # Shorthand works too
  475. # 0.12.1
  476. zvm run stable version # Run against the latest stable
  477. # 0.16.0
  478. zig version
  479. # 0.13.0
  480. ```
  481. This can be helpful if you want to test your project on a newer version of Zig
  482. without having to switch between bins, or on alternative flavor of Zig.
  483. ## How to use with alternative VMUs
  484. Make sure you switch your VMU before using `run`.
  485. ```sh
  486. zvm vmu zig mach
  487. zvm run mach-latest version
  488. # 0.14.0-dev.1911+3bf89f55c
  489. ```
  490. If you would like to run the currently set Zig, please keep using the standard
  491. `zig` command.
  492. ## Set Version Map Source
  493. ZVM lets you choose your vendor for Zig and ZLS. This is great if your company
  494. hosts its own internal fork of Zig, you prefer a different flavor of the
  495. language, like Mach.
  496. ```sh
  497. zvm vmu zig "https://machengine.org/zig/index.json" # Change the source ZVM pulls Zig release information from.
  498. zvm vmu zls https://validurl.local/vmu.json
  499. # ZVM only supports schemas that match the offical version map schema.
  500. # Run `vmu default` to reset your version map.
  501. zvm vmu zig default # Resets back to default Zig releases.
  502. zvm vmu zig mach # Sets ZVM to pull from Mach nominated Zig.
  503. zvm vmu zls default # Resets back to default ZLS releases.
  504. ```
  505. ## Use a Custom Mirror Distribution Server
  506. ZVM now lets you set your own Mirror Distribution Server. If you cannot or
  507. choose not to use the official Zig mirror list, you can host your own, or use
  508. another grouping of mirrors.
  509. ```sh
  510. zvm mirrorlist <url>
  511. # Reset to the official mirror
  512. zvm mirrorlist default
  513. ```
  514. ## Print program help
  515. Print global help information by running:
  516. ```sh
  517. zvm --help
  518. ```
  519. Print help information about a specific command or subcommand.
  520. ```sh
  521. zvm list --help
  522. ```
  523. ```
  524. NAME:
  525. zvm list - list installed Zig versions. Flag `--all` to see remote options
  526. USAGE:
  527. zvm list [command options] [arguments...]
  528. OPTIONS:
  529. --all, -a list remote Zig versions available for download, based on your version map (default: false)
  530. --vmu list set version maps (default: false)
  531. --help, -h show help
  532. ```
  533. ## Print program version
  534. ```sh
  535. zvm --version
  536. ```
  537. Prints the version of ZVM you have installed.
  538. ## Report a bug
  539. ```sh
  540. zvm bug
  541. ```
  542. Opens a prefilled issue on ZVM's GitHub repository in your browser. The report template comes with your environment already filled in: your ZVM version, settings, installed and selected Zig versions, and host details. Fill in what you did, what happened, and what you expected, then submit it yourself — `zvm` never files the issue for you.
  543. On a machine with no browser (a remote shell or a container), print the URL instead and open it elsewhere:
  544. ```sh
  545. zvm bug --print
  546. ```
  547. `$BROWSER` takes precedence over the platform's default handler if it's set.
  548. ## Shell Completion
  549. ZVM can emit a completion script for `bash`, `zsh`, `fish`, or `pwsh`
  550. (PowerShell). The script is generated from ZVM's live command tree, so it
  551. always reflects the commands and flags of the `zvm` binary you ran it with.
  552. ```sh
  553. zvm completion bash
  554. zvm completion zsh
  555. zvm completion fish
  556. zvm completion pwsh
  557. ```
  558. ### Bash
  559. Source the script for the current session:
  560. ```sh
  561. source <(zvm completion bash)
  562. ```
  563. To load it on every new shell, write it to `bash-completion`'s load path:
  564. ```sh
  565. zvm completion bash > /etc/bash_completion.d/zvm # system-wide
  566. # or for a single user:
  567. zvm completion bash > ~/.local/share/bash-completion/completions/zvm
  568. ```
  569. ### Zsh
  570. Place the script somewhere on your `$fpath` as `_zvm`. Pick a user-writable
  571. directory so you don't need `sudo`:
  572. ```sh
  573. # Plain zsh — create a user completions dir and add it to $fpath in ~/.zshrc:
  574. mkdir -p ~/.zsh/completions
  575. zvm completion zsh > ~/.zsh/completions/_zvm
  576. # Then in ~/.zshrc (before `compinit`):
  577. fpath=(~/.zsh/completions $fpath)
  578. ```
  579. If you use [Oh My Zsh](https://ohmyz.sh/), drop it into the custom completions
  580. directory instead — Oh My Zsh adds it to `$fpath` automatically:
  581. ```sh
  582. mkdir -p ~/.oh-my-zsh/custom/completions
  583. zvm completion zsh > ~/.oh-my-zsh/custom/completions/_zvm
  584. ```
  585. Then ensure `compinit` is running in your `~/.zshrc` (Oh My Zsh already does
  586. this for you):
  587. ```sh
  588. autoload -Uz compinit && compinit
  589. ```
  590. ### Fish
  591. ```sh
  592. zvm completion fish > ~/.config/fish/completions/zvm.fish
  593. ```
  594. Fish picks this up automatically on the next shell.
  595. ### PowerShell
  596. ```powershell
  597. zvm completion pwsh > $HOME/.zvm/zvm.ps1
  598. ```
  599. Then dot-source the file from your PowerShell profile (`$PROFILE`):
  600. ```powershell
  601. . "$HOME/.zvm/zvm.ps1"
  602. ```
  603. <hr>
  604. ## Option flags
  605. ### Color Toggle
  606. Enable or disable colored ZVM output. No value toggles colors.
  607. #### Enable
  608. - on
  609. - yes/y
  610. - enabled
  611. - true
  612. #### Disabled
  613. - off
  614. - no/n
  615. - disabled
  616. - false
  617. ```sh
  618. --color # Toggle ANSI color printing on or off for ZVM's output, i.e. --color=true
  619. ```
  620. ### Silence
  621. ```sh
  622. --silent # Silence everything that can be silenced, for this run only
  623. --silent=auc # Silence only the named tags (comma-separated)
  624. ```
  625. Tags:
  626. - `auc`: the automatic upgrade checker. ZVM neither contacts GitHub nor
  627. prints an upgrade notice.
  628. Tags must be attached with `=` (`zvm --silent=auc ls`). `zvm --silent auc ls`
  629. reads `auc` as the command. Put `--silent` before the command.
  630. The upgrade checker never runs for shell completion requests,
  631. `zvm completion`, or `zvm env`. To turn it off for every run, set
  632. `ZVM_DISABLE_AUC` (see [Environment Variables](#environment-variables)).
  633. ## Environment Variables
  634. - `ZVM_DEBUG` enables DEBUG logging for your executable. This is meant for
  635. contributors and developers.
  636. - `ZVM_DISABLE_AUC` Turn off the automatic upgrade checker. If you want to
  637. reenable the checker, just `unset ZVM_DISABLE_AUC`.
  638. - `ZVM_PATH` replaces the default install location for ZVM Set the environment
  639. variable to the parent directory of where you've placed the `.zvm` directory.
  640. - `ZVM_TARGET_OS` Override the target operating system for downloads (e.g.,
  641. `linux`, `macos`, `windows`, `freebsd`). Useful on platforms where Zig doesn't
  642. provide pre-built binaries for a specific version.
  643. - `ZVM_TARGET_ARCH` Override the target architecture for downloads (e.g.,
  644. `x86_64`, `aarch64`, `arm`, `riscv64`).
  645. - `ZVM_SKIP_TLS_VERIFY` Do you have problems using TLS in your environment?
  646. Toggle off verifying TLS by setting this environment variable.
  647. - By default when this is enabled ZVM will print a warning. Set this variable
  648. to `no-warn` to silence this warning.
  649. - **Danger:** with TLS verification off, anyone on the network path (a
  650. hostile Wi-Fi, a compromised proxy) can replace the Zig tarballs, minisign
  651. signatures and ZLS archives that ZVM downloads. What still
  652. protects you:
  653. - Official Zig tarballs (from ziglang.org or a community mirror) are
  654. checked against Zig's minisign signature, including the filename the
  655. signature was made for, so an attacker cannot hand you a modified build
  656. or an older build under a newer version's name.
  657. - The version lists (`index.json` and the ZLS release index) are still
  658. fetched with TLS verification even when this variable is set, and their
  659. SHA-256 checksums are checked unless you pass `--skip-shasum`.
  660. - ZLS archives are **not** signed. With this variable set, their only
  661. protection is the SHA-256 checksum; combined with `--skip-shasum`, an
  662. attacker can install an arbitrary `zls` binary.
  663. - Setting it to `no-warn` only hides the warning. It does not make
  664. downloads any safer.
  665. - `ZVM_MULTISHELL_PATH` is set by `zvm env` to the current shell's own Zig
  666. link. While it is set, `zvm use` only affects that shell.
  667. - `ZVM_MULTISHELL_DIR` overrides where `zvm env` creates per-shell links. It
  668. must be an absolute path outside `~/.zvm`.
  669. - `BROWSER` is the command `zvm bug` uses to open a report URL. Without it, ZVM falls back to the platform's default handler.
  670. ## Settings
  671. ZVM keeps its settings in `~/.zvm/settings.json` and creates the file if it
  672. doesn't exist. You can edit it by hand, use bespoke commands, or use `zvm settings` to view and
  673. change individual values. It uses jq-style paths to select settings.
  674. Bespoke commands and flags are still work. `--color` updates the same
  675. `useColor` setting, and `zvm mirrorlist` and `zvm vmu` still set your mirror
  676. list and version maps. The `alwaysInstallZLS` setting controls whether a
  677. requested ZLS installation is attempted after Zig installation fails. It
  678. defaults to `false`.
  679. ### Editing settings
  680. ```sh
  681. zvm settings
  682. ```
  683. Run `settings` in a terminal to open the editor. Use `j`/`k` or the arrow
  684. keys to move, `Enter` or `i` to edit, and `Space` to toggle a boolean. Press
  685. `r` to reset a value to its default, `w` or `Ctrl+S` to save, and `q` to
  686. quit. If you've changed something without saving it, `q` asks before
  687. quitting. Vim commands `:w`, `:q`, `:wq`, and `:q!` work too.
  688. You can also select a key with jq's dot notation and pass a value to replace
  689. it. Values are validated before anything is saved:
  690. ```sh
  691. zvm settings . # Print all settings as JSON
  692. zvm settings --json # Print all settings as JSON, even in a terminal
  693. zvm settings .useColor # Print one value
  694. zvm settings -r .mirrorListUrl # Print a string without JSON quotes
  695. zvm settings .useColor false # Validate and save a value
  696. zvm settings .mirrorListUrl disabled
  697. zvm settings .autoDedupe true # Dedupe future Zig installs automatically
  698. zvm settings --check # Check the file; exit 1 if an entry is invalid
  699. ```
  700. The path selects one setting. `.useColor`, `."useColor"`, and
  701. `.["useColor"]` all work. Settings are currently flat, so nested paths and
  702. jq filters such as `.useColor | not` aren't supported. To change a value,
  703. pass the replacement as the next argument. Quotes around a path belong to
  704. your shell, for example:
  705. ```sh
  706. zvm settings '.["useColor"]' false
  707. ```
  708. Without a terminal, `zvm settings` prints JSON. It does the same on Plan 9,
  709. where the interactive editor isn't available. Reading and setting individual
  710. values works there too.
  711. `--json` also prints a selected or updated value as JSON without the usual
  712. update prefix. It cannot be combined with `--check` or `--raw-output`.
  713. If the file has malformed JSON, a value of the wrong type, an invalid URL,
  714. or an invalid signing key, ZVM warns and uses defaults for the affected
  715. settings. It leaves your file alone so you can fix it. The editor shows the
  716. problems, and saving writes the values shown in the editor. Unknown keys are
  717. reported too, and are removed when you save.
  718. ## Uninstalling ZVM
  719. ZVM stores its binaries, installed Zig versions, and settings under
  720. `$HOME/.zvm` on Unix-like systems and `$HOME\.zvm` on Windows. Remove the
  721. installer-managed environment configuration before deleting that directory.
  722. ### Linux, BSD, macOS, and other Unix-like systems
  723. `install.sh` adds a block beginning with `# ZVM` to one of the following shell
  724. startup files:
  725. - Fish: `~/.config/fish/config.fish`
  726. - Zsh: `~/.zshenv`, `~/.zprofile`, or `~/.zshrc`
  727. - Other shells: `~/.bashrc` or `~/.profile`
  728. Remove that entire block, including the `ZVM_INSTALL` assignment and the lines
  729. that add `$HOME/.zvm/bin` and `$ZVM_INSTALL` to `PATH`. Then remove ZVM:
  730. ```sh
  731. rm -rf "$HOME/.zvm"
  732. ```
  733. Close and reopen your terminal to clear `ZVM_INSTALL` and the ZVM entries from
  734. the current environment.
  735. ### Windows PowerShell
  736. Run the following in PowerShell to remove the user-level `ZVM_INSTALL`
  737. variable, remove ZVM's two entries from the user and current-session `Path`,
  738. and delete ZVM:
  739. ```powershell
  740. $ZvmPaths = @(
  741. "$HOME\.zvm\self"
  742. "$HOME\.zvm\bin"
  743. )
  744. [Environment]::SetEnvironmentVariable(
  745. "ZVM_INSTALL",
  746. $null,
  747. [EnvironmentVariableTarget]::User
  748. )
  749. $UserPath = [Environment]::GetEnvironmentVariable(
  750. "Path",
  751. [EnvironmentVariableTarget]::User
  752. ) -split ";" | Where-Object {
  753. $_ -and $_.TrimEnd("\") -notin $ZvmPaths
  754. }
  755. [Environment]::SetEnvironmentVariable(
  756. "Path",
  757. $UserPath -join ";",
  758. [EnvironmentVariableTarget]::User
  759. )
  760. Remove-Item Env:ZVM_INSTALL -ErrorAction SilentlyContinue
  761. $env:Path = (($env:Path -split ";") | Where-Object {
  762. $_ -and $_.TrimEnd("\") -notin $ZvmPaths
  763. }) -join ";"
  764. Remove-Item -Recurse -Force "$HOME\.zvm"
  765. ```
  766. Restart open terminals and editors so they inherit the updated user
  767. environment.
  768. ## Please Consider Giving the Repo a Star ⭐
  769. <!-- Regenerated daily by .github/workflows/star-history.yml -->
  770. <a href="https://github.com/tristanisham/zvm/stargazers">
  771. <picture>
  772. <source media="(prefers-color-scheme: dark)" srcset=".github/assets/star-history-dark.svg" />
  773. <source media="(prefers-color-scheme: light)" srcset=".github/assets/star-history-light.svg" />
  774. <img alt="Star History Chart" src=".github/assets/star-history-light.svg" width="800" />
  775. </picture>
  776. </a>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.