Anchor Version Manager (AVM) - AI-Optimized Technical Reference

Overview

AVM is a version management tool for Anchor CLI that eliminates dependency conflicts in Solana development. Similar to nvm for Node.js, it allows multiple Anchor versions to coexist and switch seamlessly.

Critical Problem Context

Pre-AVM Failure Scenarios

• PATH conflicts: Wrong versions executed, causing silent build failures
• Mixed dependencies: Broken builds due to version conflicts between projects
• Team synchronization failures: "Works on my machine" issues with different Anchor versions
• CI/CD non-reproducibility: Random build artifacts from inconsistent versions
• Verifiable build impossibility: Cannot pin exact versions for security audits

Severity Indicators

• Critical: Production failures from wrong version deployments
• High: Hours wasted debugging environment instead of development
• Medium: Team productivity loss from version synchronization issues

Technical Specifications

Installation Requirements

• Rust/Cargo: Required for compilation (1-2 minutes build time)
• Git: Required for repository cloning
• Disk Space: ~200MB per Anchor version installed
• Platform: Unix-like environment (Windows requires WSL)

Installation Command

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

Critical: --force flag prevents silent installation failures

Core Operations

# Install versions
avm install latest              # ~200MB download
avm install 0.31.1             # Specific version
avm install 0.31.0-d1ca820     # Exact commit for verifiable builds

# Switch versions (manual only - no auto-switching)
avm use 0.31.1

# List installed versions
avm list

# Verify active version
anchor --version

Configuration for Production

Team Synchronization Pattern

## Development Setup
1. Install AVM: `cargo install --git https://github.com/coral-xyz/anchor avm --force`
2. Install project version: `avm install 0.31.1 && avm use 0.31.1`
3. Build: `anchor build`

Version Validation Script

#!/bin/bash
required_version="0.31.1"
current_version=$(anchor --version | cut -d' ' -f2)

if [ "$current_version" != "$required_version" ]; then
    echo "Wrong Anchor version. Run: avm use $required_version"
    exit 1
fi

CI/CD Configuration

# Pin exact versions - NEVER use 'latest' in CI
- name: Install AVM
  run: cargo install --git https://github.com/coral-xyz/anchor avm --force
- name: Install specific Anchor version
  run: |
    avm install 0.31.1
    avm use 0.31.1
- name: Build verifiable
  run: anchor build --verifiable

Resource Requirements

Time Investment

• Initial setup: 5-10 minutes (including Rust compilation)
• Version switching: <5 seconds per switch
• Team onboarding: Reduced from hours to minutes with proper documentation

Expertise Requirements

• Minimum: Basic command line familiarity
• Recommended: Understanding of version management concepts
• Advanced: Knowledge of verifiable builds for production deployments

Storage Management

• Each version: ~200MB disk space
• Recommended retention: Keep last 3-4 versions
• Manual cleanup: rm -rf ~/.avm/old-version (no auto-cleanup available)

Critical Warnings

What Official Documentation Doesn't Tell You

Windows Native Installation

• Breaking Point: Random compilation errors and PATH conflicts
• Solution: Use WSL instead of native Windows installation
• Cost: Hours of debugging vs. 10 minutes WSL setup

PATH Conflicts with Existing Installations

• Failure Mode: anchor --version shows different version than avm list
• Root Cause: Multiple Anchor installations in PATH
• Solution: Remove all non-AVM installations first

npm uninstall -g @project-serum/anchor-cli
cargo uninstall anchor-cli

Verifiable Build Requirements

• Critical: Production deployments need exact commit hashes
• Failure: Using version tags produces non-reproducible builds
• Solution: Use commit-specific installs: avm install 0.31.0-d1ca820

Common Failure Modes

"Command not found: avm"

• Cause: ~/.cargo/bin not in PATH
• Fix: Add to shell config and restart terminal

export PATH="$HOME/.cargo/bin:$PATH"

"Command not found: anchor" after installation

• Cause: Version installed but not activated
• Fix: avm use <version>

Build artifacts differ between machines

• Cause: Using latest instead of pinned versions
• Fix: Pin exact versions in all environments

Decision Support Information

AVM vs Alternatives Comparison

Method	Multiple Versions	Verifiable Builds	Team Sync	CI/CD Reliability
AVM	✅ Seamless	✅ Exact commits	✅ Version pinning	✅ Reproducible
NPM Package	❌ Single version	❌ No control	❌ Version conflicts	❌ Outdated versions
Cargo Direct	❌ Reinstall required	❌ Dependency drift	❌ Impossible sync	❌ Non-reproducible
Manual Compilation	❌ PATH hell	⚠️ Complex setup	❌ Environment drift	❌ Time intensive

When AVM Is Worth The Investment

• Multiple Solana projects with different Anchor requirements
• Team development requiring version synchronization
• Production deployments needing verifiable builds
• CI/CD pipelines requiring reproducible builds

When AVM May Be Overkill

• Single project with stable Anchor version
• Prototype development with no production requirements
• Learning environments where version consistency isn't critical

Implementation Checklist

Initial Setup

• Install Rust if not present
• Install AVM with --force flag
• Verify PATH includes ~/.cargo/bin
• Install and activate required Anchor version
• Test with anchor --version

Team Integration

• Document required version in README
• Add version validation to build scripts
• Remove conflicting Anchor installations
• Test installation process on team machines
• Update CI/CD to pin versions

Production Preparation

• Identify exact commit hash for verifiable builds
• Test build reproducibility across environments
• Document deployment version requirements
• Implement version verification in deployment scripts

Operational Intelligence

Hidden Costs

• Storage: 2GB+ for multiple versions (manual cleanup required)
• Team Training: Initial setup documentation and troubleshooting
• CI/CD Updates: Modification of existing build pipelines

Success Metrics

• Zero "works on my machine" issues related to Anchor versions
• Reproducible build artifacts across all environments
• Minutes instead of hours for new team member environment setup

Community and Support Quality

• Official Recommendation: Anchor documentation recommends AVM
• Active Maintenance: Regular updates in Anchor repository
• Community Support: Discord #dev-support and Solana Stack Exchange
• Documentation Quality: Comprehensive with working examples