AVM (Anchor Version Manager) - Technical Reference

Core Problem

Anchor version conflicts cause "works on my machine" build failures. Teams waste entire afternoons debugging version mismatches between Anchor CLI versions (0.29 vs 0.30+), with breaking changes destroying builds.

Solution Overview

AVM manages multiple Anchor CLI versions per project, similar to nvm for Node.js. Enables version isolation, verifiable builds, and team coordination.

Configuration

Installation Requirements

• Rust via rustup (mandatory - package managers break AVM compilation)
• Git (AVM pulls from GitHub)
• Solana CLI (install before AVM to avoid confusing error messages)
• Platform: Use WSL on Windows (native Windows support broken)

Installation Command

cargo install --git https://github.com/coral-xyz/anchor avm --force

• --force flag required for reinstalls after failures
• Compilation time: 5-25 minutes depending on dependency rebuilds
• Binary installed to ~/.cargo/bin/avm

Version Management Commands

avm install 0.30.1    # Install specific version
avm use 0.30.1        # Switch to version (per terminal session)
avm list              # Show installed versions
avm install latest    # Install bleeding edge (often broken)

Critical Warnings

Installation Failure Modes

1. "No such file or directory" - Git missing or PATH corrupted
2. Compilation errors - Old Rust version (run rustup update)
3. 15+ minute timeouts - Network issues during source compilation
4. Version conflicts - Multiple Anchor installs fighting for control

PATH Management Issues

• AVM only affects current terminal session
• Must run avm use X.X.X in every new terminal
• Common PATH conflicts with npm installs and cargo direct installs

Production Critical Issues

• Version X.X.X not installed after successful install - AVM state corruption
• Wrong version after avm use - Multiple installation sources conflict
• Windows PATH handling broken - Use WSL instead

Resource Requirements

Time Investment

• Initial setup: 2-30 minutes (depending on compilation issues)
• Per-project setup: 2 minutes (avm install X.X.X && avm use X.X.X)
• Debugging broken installs: 2+ hours (nuclear option: delete ~/.avm and reinstall)

Disk Space

• Wasteful: Each version ~100MB+ in ~/.avm/versions/
• Storage locations: ~/.avm/bin/ (binaries), ~/.avm/versions/ (tracking)

Expertise Requirements

• Basic Rust toolchain knowledge
• Understanding of PATH manipulation
• Debugging shell environment issues

Troubleshooting Decision Tree

When avm install latest Fails

1. Check which git - install git if missing
2. Verify ~/.cargo/bin in PATH
3. Restart terminal (PATH changes need pickup)
4. Try specific version instead of latest

When anchor --version Shows Wrong Version

1. Remove npm installations:

   npm uninstall -g @project-serum/anchor-cli
   npm uninstall -g @coral-xyz/anchor-cli
   

2. Verify which anchor points to ~/.avm/bin/anchor
3. Nuclear option: rm -rf ~/.avm and reinstall

When Installation Takes Forever

• AVM compiles from source by default (15+ minutes)
• Pre-built binaries available since v0.31.0 for:
  • aarch64-apple-darwin (M1/M2 Mac)
  • x86_64-unknown-linux-gnu (Intel Linux)
  • x86_64-apple-darwin (Intel Mac)
  • x86_64-pc-windows-msvc (Windows)
• Unsupported platforms require --from-source flag

Breaking Points and Failure Scenarios

AVM Self-Destruction Triggers

• Mixing cargo install with AVM installs
• Rust toolchain updates (breaks compiled binaries)
• Intel/ARM Mac switches with different compiled binaries
• Node 18.2.0 specific PATH conflicts

Team Coordination Failures

• Different team members on different Anchor versions hit different bugs
• No version documentation leads to onboarding nightmares
• Version leakage between projects causes random build failures

Alternative Approaches Comparison

Approach	Installation Pain	Version Management	Team Coordination	Reliability
AVM	High (compile hell)	Excellent	Easy (avm use X.X.X)	Usually fixable
Cargo Direct	Medium (one compile)	None (single version)	Manual nightmare	Requires reinstall when broken
NPM	Low (when works)	None (single version)	Worse nightmare	Unreliable

Production Deployment Considerations

Verifiable Builds

• Install from specific commit hashes for exact reproducibility
• Required when deploying contracts with real money at stake
• Command: avm install <commit-hash>

Version Pinning Strategy

• Document exact Anchor version in README
• Pin team to same version or accept build chaos
• Most projects use 0.30.1 (stable, upgrade risk too high)

Common Misconceptions

1. "AVM is just like nvm" - Similarity ends at concept; AVM has unique failure modes
2. "Latest version is best" - Latest often broken, use stable versions
3. "One installation works everywhere" - Per-terminal session scope causes confusion
4. "Windows support works" - Native Windows support fundamentally broken

Success Criteria

• anchor --version shows expected version after avm use
• Team members can reproduce builds with same version
• Projects can upgrade/downgrade Anchor versions without conflicts
• New developers can onboard without environment debugging

Nuclear Options (When All Else Fails)

1. Delete ~/.avm entirely and reinstall (5 minutes vs 2+ hours debugging)
2. Direct cargo install for single-version setups
3. Docker containers with known-working versions
4. Switch to different platform (WSL, Linux VM)

Time limit: Don't spend more than 2 hours debugging AVM installation - it's meant to save time, not waste it.