Version Management (agave-install / avm)

Q: Does agave-install replace solana-install?

Yes - use Anza release URLs (release.anza.xyz) for Agave 4.x onward.

Q: How do I pin Rust 1.91.1?

Add rust-toolchain.toml with channel = "1.91.1" at the repo root.

Q: Can two repos use different Anchor versions?

Yes - run avm use when switching directories or use direnv hooks.

Q: What if anchor build warns about version mismatch?

Align avm use, Anchor.toml anchor_version, and anchor-lang crate version to the same release.

Q: How do I upgrade Agave safely?

Install new version, run full anchor test and deploy dry-run on devnet, then update team docs.

Q: How do I uninstall old Agave versions?

agave-install list then remove unused directories per Anza docs, or reinstall clean channel.

Q: 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.

Q: How do I pin @solana/kit?

Use package.json "@solana/kit": "7.0.0" - separate from Agave/Anchor pins.

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 --version

When 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 latest install 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.toml

What this demonstrates:

agave-install init selects the validator/CLI release channel.
avm use switches the anchor binary on PATH.
Anchor.toml anchor_version warns when CLI mismatch would corrupt IDL builds.

Deep Dive

How It Works

agave-install downloads release artifacts into ~/.local/share/solana/install/active_release.
Shell PATH prepends that bin directory for solana, cargo-build-sbf, etc.
avm stores multiple Anchor CLI builds under ~/.avm and symlinks the active one.
Rust itself is managed separately via rustup (pin 1.91.1 with rust-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 list

Gotchas

PATH shadowing - Homebrew solana overrides Agave install. Fix: which solana and reorder PATH.
Forgotten avm in CI - Docker image has Anchor 0.30 while repo needs 0.32.1. Fix: explicit avm use step 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: commit rust-toolchain.toml with 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.

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.

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 --version

When 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 latest install 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.toml

What this demonstrates:

agave-install init selects the validator/CLI release channel.
avm use switches the anchor binary on PATH.
Anchor.toml anchor_version warns when CLI mismatch would corrupt IDL builds.

Deep Dive

How It Works

agave-install downloads release artifacts into ~/.local/share/solana/install/active_release.
Shell PATH prepends that bin directory for solana, cargo-build-sbf, etc.
avm stores multiple Anchor CLI builds under ~/.avm and symlinks the active one.
Rust itself is managed separately via rustup (pin 1.91.1 with rust-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 list

Gotchas

PATH shadowing - Homebrew solana overrides Agave install. Fix: which solana and reorder PATH.
Forgotten avm in CI - Docker image has Anchor 0.30 while repo needs 0.32.1. Fix: explicit avm use step 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: commit rust-toolchain.toml with 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.

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.

Version Management (agave-install / avm)

Search Documentation

Version Management (agave-install / avm)