{"id":31585074,"url":"https://github.com/weezy20/zv","last_synced_at":"2026-04-05T21:17:32.488Z","repository":{"id":317686236,"uuid":"1051619221","full_name":"weezy20/zv","owner":"weezy20","description":"Blazing fast, cross-platform zig version manager \u0026 project starter kit","archived":false,"fork":false,"pushed_at":"2026-04-05T20:22:38.000Z","size":1374,"stargazers_count":36,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-05T20:32:52.679Z","etag":null,"topics":["programming-languages","toolchain","version-manager","zig","zig-package"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/zv","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/weezy20.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-06T11:29:49.000Z","updated_at":"2026-04-05T20:22:36.000Z","dependencies_parsed_at":"2025-10-24T19:09:15.808Z","dependency_job_id":null,"html_url":"https://github.com/weezy20/zv","commit_stats":null,"previous_names":["weezy20/zv"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/weezy20/zv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weezy20%2Fzv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weezy20%2Fzv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weezy20%2Fzv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weezy20%2Fzv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/weezy20","download_url":"https://codeload.github.com/weezy20/zv/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weezy20%2Fzv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31450287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["programming-languages","toolchain","version-manager","zig","zig-package"],"created_at":"2025-10-06T01:27:02.977Z","updated_at":"2026-04-05T21:17:32.481Z","avatar_url":"https://github.com/weezy20.png","language":"Rust","funding_links":[],"categories":["Fundamentals"],"sub_categories":["Package and Version Manager"],"readme":"\u003ch1 align=\"center\"\u003e\nzv (zig version)\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo/zv.png\" alt=\"zv logo\" width=\"400\" /\u003e\n\u003c/p\u003e\n\n`zv` is a blazing-fast, cross-platform, simple-to-use compiler toolchain manager for Zig, written in Rust. `zv` aims to be a fast and dependable manager for Zig and ZLS, both system-wide and project-specific, with either inline syntax `zig +\u003cversion\u003e` or by using a `.zigversion` file in your project root. A `version` can be a semver, `master`, or `latest` for the latest stable. These values are fetched from the cached Ziglang download index available at \u003ca href=\"https://ziglang.org/download/index.json\"\u003eZig official index\u003c/a\u003e.\n\nWith `zv` binaries, you can now build with the master branch without changing your default system Zig version:\n```sh\nzig +master build\n```\nCaching is built-in, so you never have to wait any longer than strictly necessary.\n\nYou can also specify a version number, e.g., `zig +0.15.1`. With `zv`, you also have the option of pinning per-project Zig versions using a `.zigversion` file, which takes the same format as `+` would for inline Zig commands. You can have a project with these contents:\n\n```py\n# file .zigversion\n0.15.2\n```\nwhich will always use version `0.15.1` when you run any `zig` command inside it. How cool is that?\n\nIt also doubles as a project template starter, providing multiple variants of a Zig project, from a barebones template with a very trimmed-down `build.zig` and `main.zig` file, or the standard Zig project template. Find out more with `zv init --help`.\n\n`zv` uses randomized ranked community mirrors for downloads (can be overridden to use ziglang.org with -f), as that's the official recommendation, with `minisign` and `shasum` verification done before any toolchain is installed. Future versions should bring in an optimization to rank the mirrors based on speed so that faster mirrors are selected more often without user intervention.\n\n## Upgrading from v0.9.x — Breaking Changes (Linux / macOS)\n\n\u003e **Windows users**: nothing changes for you. Skip this section.\n\nThis release adopts the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) on Linux and macOS. Files are now split across purpose-appropriate directories instead of living under a single `~/.zv` root:\n\n| Role | Old path | New path |\n|------|----------|----------|\n| Data (binaries, versions) | `~/.zv/` | `~/.local/share/zv/` |\n| Config (`zv.toml`) | `~/.zv/zv.toml` | `~/.config/zv/zv.toml` |\n| Cache (index, mirrors, downloads) | `~/.zv/` | `~/.cache/zv/` |\n| Public bin (symlinks) | `~/.zv/bin/` in PATH | `~/.local/bin/` (usually already in PATH) |\n\n### Who is affected\n\nAny Linux or macOS user who:\n- installed zv **before this release**, **and**\n- does **not** have `ZV_DIR` set in their environment.\n\n**If you have `ZV_DIR` set, you are not affected.** `ZV_DIR` still acts as a self-contained root for all paths — identical to the old behaviour.\n\n### What breaks if you do nothing\n\n- zv no longer sees your installed Zig versions — they are still at `~/.zv/versions/` but zv now looks in `~/.local/share/zv/versions/`.\n- Your active Zig selection (`~/.zv/zv.toml`) is invisible to the new config path.\n- The welcome message says **\"Setup incomplete. Run `zv sync`\"** even though your old install works fine.\n- `zv sync` / `zv use` / `zv install` operate on the new empty state, not your old one.\n- Your shell RC still sources `~/.zv/env`, keeping the old `~/.zv/bin` in `PATH` — so `zig` keeps working via the old shim, but zv commands increasingly diverge from it.\n- Running `zv setup` creates a second installation alongside the old one.\n\n### Option A — Migrate to XDG (recommended)\n\nRun the following once after upgrading:\n\n```sh\n# 1. Create new XDG directories\nmkdir -p ~/.local/share/zv ~/.config/zv ~/.cache/zv\n\n# 2. Move installed Zig versions (the bulk of the data)\nmv ~/.zv/versions ~/.local/share/zv/versions\n\n# 3. Copy config\ncp ~/.zv/zv.toml ~/.config/zv/zv.toml 2\u003e/dev/null || true\n\n# 4. Copy cache files (zv will re-fetch these if missing, but saves a sync)\ncp ~/.zv/index.toml   ~/.cache/zv/index.toml   2\u003e/dev/null || true\ncp ~/.zv/mirrors.toml ~/.cache/zv/mirrors.toml 2\u003e/dev/null || true\ncp ~/.zv/master       ~/.cache/zv/master        2\u003e/dev/null || true\n\n# 5. Re-run zv sync to place the binary and create ~/.local/bin symlinks\nzv sync\n\n# 6. Remove the old source line from your shell RC\n#    Look for:  source ~/.zv/env   or   . ~/.zv/env\n#    Delete or comment it out, then open a new shell.\n\n# 7. Verify everything looks right\nzv          # should show \"✔ Ready to Use\"\nzv list     # should show your previously installed versions\n\n# 8. (Optional) Remove the old directory once satisfied\nrm -rf ~/.zv\n```\n\n### Option B — Keep the old layout (zero disruption)\n\nAdd `ZV_DIR` to your shell profile to restore the pre-XDG behaviour:\n\n```sh\n# Add to ~/.bashrc, ~/.zshenv, ~/.zprofile, or equivalent\nexport ZV_DIR=\"$HOME/.zv\"\n```\n\nWhen `ZV_DIR` is set, zv uses it as a self-contained root for **all** paths (data, config, cache) and does not apply XDG splitting. Everything works exactly as before — no files need to move.\n\n### Why no automatic migration?\n\nSilently moving files and re-patching shell configs without user consent is worse than doing nothing. `ZV_DIR` is a zero-effort escape hatch for users who don't want to migrate right now. Automatic migration will be added in a follow-up release once the XDG layout has stabilised.\n\n### Symptom reference\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| \"Setup incomplete. Run `zv sync`\" on startup | `~/.local/share/zv/bin/zv` does not exist yet | Run Option A or set `ZV_DIR` |\n| `zig` works but `zv list` shows nothing | Old `~/.zv/bin` is still in `PATH`; new state is empty | Same |\n| `zv setup` creates a second empty installation | New paths don't see `~/.zv` | Same |\n| `zv` shows \"not in PATH\" despite `zig` working | `source_set` now checks `~/.local/bin`, not `~/.zv/bin` | Run `zv setup` after migration, or set `ZV_DIR` |\n| `~/.zv` still on disk after upgrading | No automatic cleanup | Safe to delete once migrated |\n\n---\n\n## Installation\n\nThere are two primary paths: fetch a prebuilt binary or build from source. Either way, finish with `zv sync` — that's all you need. `zv setup` is a legacy fallback covered at the end.\n\n### Option 1 — Prebuilt binary (Recommended)\n\n**Linux/macOS:**\n```sh\ncurl -fsSL https://github.com/weezy20/zv/releases/latest/download/install.sh | bash\n```\n\n**Windows (PowerShell):**\n```powershell\nirm https://github.com/weezy20/zv/releases/latest/download/install.ps1 | iex\n```\n\nIf you get an execution policy error on Windows:\n```powershell\npowershell -ExecutionPolicy Bypass -Command \"irm https://github.com/weezy20/zv/releases/latest/download/install.ps1 | iex\"\n```\n\nThe script downloads the release binary, places it at `~/.local/share/zv/bin/zv`, and creates a symlink at `~/.local/bin/zv` (Linux/macOS) or installs to `%USERPROFILE%\\.zv\\bin\\zv.exe` (Windows). Then finish with:\n\n```sh\nzv sync\n```\n\n### Option 2 — Build from source\n\n```sh\n# Clone and build\ncargo build --release\n\n# Sync using the freshly built binary\n./target/release/zv sync\n```\n\nOr via `cargo install`:\n```sh\ncargo install zv\n~/.cargo/bin/zv sync\ncargo uninstall zv   # optional: clean up the cargo copy; the live binary is now in ZV_DIR/bin\n```\n\n**HomeBrew / NPM / Bun:**\n```sh\nbrew install weezy20/tap/zv\n\nnpm install -g @weezy20/zv\n# or\nbun i -g @weezy20/zv\n```\n\n---\n\n### `zv setup` — legacy PATH configuration (last resort)\n\nOn **Linux**, `zv setup` is a no-op — run `zv sync` instead.\n\nOn **macOS** (non-XDG layout) or **Windows**, if `zv sync` warns that your PATH isn't configured, run `zv setup`. It will make the following changes to your system:\n\n- **Creates** a shell environment file at `$ZV_DIR/env`\n- **Appends** a `source $ZV_DIR/env` line to your shell RC file (e.g. `~/.bashrc`, `~/.zshrc`, `~/.zprofile`)\n\nTo preview these changes without applying them:\n```sh\nzv setup --dry-run\n```\n\n## Updating `zv` \n\n**Simple update (Recommended):**\n```sh\nzv update # Installs latest stable release on supported targets*.\n```\n\nThis command checks for new releases on GitHub and updates `zv` in place. It works whether you're running from `ZV_DIR/bin/zv` or from an external location (like cargo install). \n\n**Options:**\n```sh\nzv update --force  # Force reinstall even if already on the latest version\nzv upgrade         # Alias for update\nzv update --rc     # Update to latest pre-release (release candidate) version\n```\n\n\n\n\u003cdetails\u003e\n\u003csummary\u003eAlternative update methods:\u003c/summary\u003e\n\nIf you have the repo cloned or are using a cargo-installed binary:\n```sh\n# Build new version and update the binary in ZV_DIR/bin\ncargo run --release -- sync\n\n# Or if you installed from crates.io, install it and sync\ncargo install zv --force\nzv sync\n# or if you already have ZV_DIR/bin in path\n~/.cargo/bin/zv sync # $CARGO_HOME/bin/zv sync\n```\n\u003c/details\u003e\n\n## Usage\n\nAll `zv` data follows the XDG Base Directory Specification on Linux/macOS:\n\n**Default locations (Linux/macOS):**\n- Data (binaries, versions): `$HOME/.local/share/zv`\n- Config (`zv.toml`): `$HOME/.config/zv`\n- Cache (index, mirrors, downloads): `$HOME/.cache/zv`\n- Public bin (symlinks): `$HOME/.local/bin`\n\n**Default locations (Windows):**\n- All data: `%USERPROFILE%\\.zv`\n\nYou can override the data directory by setting the `ZV_DIR` environment variable (falls back to pre-XDG self-contained layout).\n\n## Use `zv` for project creation:\n\n```sh\nzv init [project_name]                 # Create a new Zig project with a name\nzv init                                # Create a new Zig project in the current working directory\nzv init --zig | -z                     # Create a new Zig project using the standard template provided by `zig init`\n# Create a zig project with build.zig.zon:\nzv init -p | --zon | --package  \u003c?name\u003e      # Create a zig project in current directory with build.zig.zon or with name if provided\n# Note: this requires an active zig version \u003e= 0.12.0 where build.zig.zon support was introduced\n\n```\n\u003eNote: `zv init` will use the `build.zig` that's present in [templates/build.zig](templates/lean_build.zig) which is checked to work against minimum zig version specified in [templates/.zigversion](templates/.zigversion). If you want to use a different zig version, set it as active zig and use `zv init -z` or `zig init` directly.\n\n## Use `zv` as your Zig compiler toolchain manager:\n\n```sh\n# Version selection - basic usage\n# pass in -f or --force-ziglang to download using `ziglang.org` instead of community mirrors (default \u0026 recommended)\nzv use \u003cversion | master | stable | latest\u003e # Select a Zig version to use. Can be a semver, master (branch)\nzv use 0.13.0                               # Use a specific semantic version\nzv use 0.14 -f                              # Use a version (auto-completes to 0.14.0) \u0026 downloads from `ziglang.org` due to -f\nzv use master                               # Use master branch build (queries network to find the latest master build)\nzv use stable                               # Use latest stable release (refers to cached index)\nzv use latest                               # Use latest stable release (queries network to fetch the latest stable)\nzv install \u003cversion,*\u003e [-f ]                # Install one or more Zig versions without switching to it. Use -f to download from ziglang.org instead of community mirrors.\nzv i 0.15.1,0.14.0,master                   # Install multiple versions at once using a comma-separated list\n\n# Per-project Zig config\nzig +\u003cversion\u003e [...zig args]            # Run Zig using a specific \u003cversion\u003e (fetches and downloads version if not present locally)\nzig +master [...zig args]               # Run Zig using master build. (If already cached, no download, but a network request is made to verify version)\nzig [...zig args]                       # Uses current configured Zig or prefers version from `.zigversion` file in the repository adjacent to `build.zig`.\n\n# Management commands\nzv list  | ls                          # List installed Zig versions\nzv clean | rm                          # Remove Zig versions interactively. Additionally cleans up downloads cache, temporary download artifacts.\nzv clean | rm \u003cversion | all\u003e          # Clean up all zv-managed installations using `all` or just a single one (e.g., zv clean 0.14).\nzv clean 0.14,0.14.0                   # Clean up multiple Zig installations using a comma-separated list.\nzv clean --except \u003cversion,*\u003e          # Clean up every version except the version mentioned as argument to --except \u003cversion\u003e where \u003cversion\u003e maybe a comma separated list of ZigVersions. E.g. (zv clean --except 0.14.1,master@0.16.0-dev.565+f50c64797,stable@0.15.1)\nzv rm master                           # Clean up the `master` branch toolchain.\nzv rm master --outdated                # Clean up any older master versions in the master folder that don't match latest `master`\nzv setup                               # Set up shell environment for zv with interactive prompts (use --no-interactive for automation)\nzv sync                                # Resync community mirrors list from [ziglang.org/download/community-mirrors.txt]; also force resync of index to fetch latest nightly builds. Replaces the zv binary in data dir if outdated against current invocation.\nzv upgrade | update                    # Update zv to the latest release only if present in GH Releases: https://github.com/weezy20/zv/releases\nzv help                                # Detailed instructions for zv. Use `--help` for long help or `-h` for short help with a subcommand.\nzv uninstall                           # Uninstall zv completely by attempting to remove ZV_DIR.\n```\n\n`minisign` verification is done using [jedisct1/rust-minisign-verify](https://github.com/jedisct1/rust-minisign-verify) — a small minisign library in pure Rust.\n\nIt also supports `NO_COLOR` for non-TTY environments.\n\nI hope you enjoy using it! ♥\n\n\n---\n### Customizing ZV behaviour:\n\n### 🔧 Environment Variables for customizing zv\n\n| Variable                  | Description                                                                                                                | Default / Notes                                                                 |\n| ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |\n| **`ZV_LOG`**              | Sets the log level (same as `RUST_LOG`). If set, logging follows the specified level.                                      | Inherits `RUST_LOG` behavior                                                    |\n| **`ZV_DIR`**              | Overrides the data directory for `zv`. When set, all paths (data, config, cache) live under this directory.               | Linux/macOS: `$XDG_DATA_HOME/zv` (default `$HOME/.local/share/zv`). Windows: `%USERPROFILE%\\.zv`                                      |\n| **`ZV_INDEX_TTL_DAYS`**   | Number of days between automatic [index](https://ziglang.org/download/index.json) syncs.                                   | **21 days** — Using `master` or `latest` in inline mode use a shorter cache duration of just 1 day unlike `use` which will always fetch `master` \u0026 `latest` from network, so practically, you never have to worry about setting this variable yourself. |\n| **`ZV_MIRRORS_TTL_DAYS`** | Number of days before refreshing the mirrors list. Broken mirrors degrade automatically. Use `zv sync` to force refresh. | **21 days** — mirrors and index can be resynced immediately with `zv sync`. `master` relies on latest builds \u0026 so does `latest` and some community mirrors may not have it available; `zv` will retry other mirrors in that case.      |\n| **`ZV_MAX_RETRIES`**      | Maximum number of retry attempts for downloads when a download fails.                                                      | **3 retries** — If a download fails, `zv` will retry up to this many times before giving up.                                                   |\n| **`NO_COLOR`**            | If set, disables color output in all zv commands.                                                                          | No color output; useful for non-TTY environments or scripts.                    |\n|**`ZV_FETCH_TIMEOUT_SECS`**   | Request timeout to use for network operations requiring fetching index/mirrors list from `ziglang.org`.                | Default 4 seconds for most operations.\n\n---\n\n### Tips:\n- If you prefer some mirrors to others, you can put it as `rank = 1` on your preferred mirrors (Default is rank 1 for all mirrors) or lower the rank of mirrors that you don't want. `rank` is a range from 1..255, lower is better and more preferred when doing random selection. The mirrors file is generated at `$XDG_CACHE_HOME/zv/mirrors.toml` (default `~/.cache/zv/mirrors.toml`)\n\n- Currently `zv use master` will only install the master as present in zig-index. This means that older master installations still remain under the masters folder and can be selected via `zv use master@\u003colder master version\u003e` which can be obtained via `zv ls`. Note, installing older master versions like this may work now (zv v0.6.0 onwards): `zv i \u003cpre-release version\u003e` or `zv use \u003cpre-release version\u003e` if some mirror has the build, it'll be fetched.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweezy20%2Fzv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweezy20%2Fzv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweezy20%2Fzv/lists"}