Version Management (agave-install / avm)
Pin Agave/Solana CLI and Anchor versions with agave-install and avm so every machine and CI job compiles and deploys against the same runtime.
Recipe
Quick-reference recipe card - copy-paste ready.
agave-install init 4.1.1
solana --version
avm install 0.32.1
avm use 0.32.1
anchor --versionWhen to reach for this:
- Upgrading the team to Agave 4.1.1 / CLI 3.0.10.
- Switching between repos that require different Anchor versions.
- Reproducing a production deploy environment locally.
- Fixing CI after a silent
latestinstall broke builds.
Working Example
# Pin Agave / Solana CLI
sh -c "$(curl -sSfL https://release.anza.xyz/v4.1.1/install)"
agave-install init 4.1.1
solana --version
# Pin Anchor via avm
cargo install --git https://github.com/coral-xyz/anchor avm --locked --force
avm install 0.32.1
avm use 0.32.1
anchor --version
# Per-project Anchor.toml enforces CLI for anchor commands
grep '^anchor_version' Anchor.toml || echo 'anchor_version = "0.32.1"' >> Anchor.tomlWhat this demonstrates:
agave-install initselects the validator/CLI release channel.avm useswitches theanchorbinary on PATH.Anchor.tomlanchor_versionwarns when CLI mismatch would corrupt IDL builds.
Deep Dive
How It Works
agave-installdownloads release artifacts into~/.local/share/solana/install/active_release.- Shell PATH prepends that
bindirectory forsolana,cargo-build-sbf, etc. avmstores multiple Anchor CLI builds under~/.avmand symlinks the active one.- Rust itself is managed separately via
rustup(pin 1.91.1 withrust-toolchain.toml).
Pinning Checklist
| Layer | Tool | Pin method |
|---|---|---|
| Validator/CLI | agave-install | init 4.1.1 |
| Anchor CLI | avm | use 0.32.1 |
| anchor-lang crate | Cargo.toml | 0.32.1 |
| Rust compiler | rustup | rust-toolchain.toml |
bash Notes
# List installed Agave releases
agave-install list
# List installed Anchor versions
avm listGotchas
- PATH shadowing - Homebrew
solanaoverrides Agave install. Fix:which solanaand reorder PATH. - Forgotten avm in CI - Docker image has Anchor 0.30 while repo needs 0.32.1. Fix: explicit
avm usestep in pipeline. - anchor-lang mismatch - CLI 0.32.1 with crate 0.30.x fails macro expansion. Fix: bump all Anchor crates together.
- Updating mid-sprint without announcement - breaks pairing sessions. Fix: document upgrades in team changelog.
- rustup default stable drift - new stable breaks
cargo build-sbf. Fix: commitrust-toolchain.tomlwith 1.91.1.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
rust-toolchain.toml only | Rust-only services | Full Solana CLI pinning |
| Nix / Docker dev shells | Hermetic team environments | Quick solo laptop setup |
mucho version helpers | Foundation template repos | Custom multi-repo layouts |
| Manual tarball extract | Air-gapped installs | Normal internet-connected dev |
FAQs
Does agave-install replace solana-install?
Yes - use Anza release URLs (release.anza.xyz) for Agave 4.x onward.
How do I pin Rust 1.91.1?
Add rust-toolchain.toml with channel = "1.91.1" at the repo root.
Can two repos use different Anchor versions?
Yes - run avm use when switching directories or use direnv hooks.
What if anchor build warns about version mismatch?
Align avm use, Anchor.toml anchor_version, and anchor-lang crate version to the same release.
How do I upgrade Agave safely?
Install new version, run full anchor test and deploy dry-run on devnet, then update team docs.
Does avm manage anchor-lang crate?
No - only the CLI binary. Cargo.toml still pins program dependencies.
How do I uninstall old Agave versions?
agave-install list then remove unused directories per Anza docs, or reinstall clean channel.
Should CI call agave-install every job?
Cache the install directory keyed on version 4.1.1 for speed; verify with solana --version each run.
What about solana-verify version?
Install matching release alongside Agave when using verifiable build pipelines.
How do I pin @solana/kit?
Use package.json "@solana/kit": "7.0.0" - separate from Agave/Anchor pins.
Related
- Toolchain Overview - what each tool does
- Building Programs (cargo build-sbf) - compile after pinning
- Toolchain Best Practices - team policy
- Editor & rust-analyzer Setup - IDE uses same Rust pin
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.