Anchor Version Manager (AVM) - Stop Fighting With Anchor Installs

Before AVM, managing Anchor versions was a nightmare. You'd have one project that needed Anchor 0.29.0, another that broke unless you used 0.30.1, and your latest side project that required bleeding-edge 0.31.x features. Switching between them meant manually installing and uninstalling Anchor versions, which inevitably led to:

• PATH conflicts where the wrong version was being used
• Broken builds because dependencies got mixed up
• Hours wasted debugging environment issues instead of writing Solana programs
• Team members using different versions and builds mysteriously failing in CI

AVM fixes this the same way nvm fixes Node.js version hell. Install multiple Anchor versions, switch between them with a single command, and stop losing your mind over dependency management.

What Actually Breaks Without AVM

Version Lock-In Hell

You start a project with Anchor 0.29.0. Six months later, you want to use a new feature from 0.31.0, but updating breaks half your existing code. With AVM, you can keep 0.29.0 for the old project and use 0.31.0 for new features.

Verifiable Build Requirements

If you're building anything users will actually interact with, you need verifiable builds. This means using exact Anchor versions, not "whatever was latest when I ran cargo install." AVM lets you pin exact versions and even install from specific Git commits.

Team Synchronization Issues

"Works on my machine" becomes "works with my Anchor version." AVM makes it trivial to ensure everyone on the team uses the exact same Anchor version. Add the version to your README and everyone runs avm use 0.31.1.

CI/CD Reproducibility

Building different binaries from the same source code depending on which Anchor version the CI runner happened to have installed is a recipe for production bugs. With AVM, your CI scripts can pin the exact version: avm install 0.31.1 && avm use 0.31.1.

Integration Reality Check

AVM works with your existing Solana toolchain setup. It doesn't care about your Solana CLI version or how you installed Rust. It just manages the anchor binary and gets out of your way.

The official Anchor docs recommend AVM installation because the alternatives (npm package, cargo direct install) all have gotchas that waste your time. The npm package is often outdated, and cargo installs can conflict with system packages.

Installing AVM is pretty straightforward, assuming your Rust setup isn't completely fucked. If you don't have Rust installed yet, you'll need it first - but if you're doing Solana development and don't have Rust, you've got bigger problems than version management.

Prerequisites (The Boring But Necessary Stuff)

You need:

• Rust/Cargo: Obviously. If cargo --version doesn't work, install Rust first.
• Git: For cloning repos during install. If you don't have git, what are you even doing?
• A brain: Windows users need WSL. Trust me on this one.

Don't try to install AVM directly on Windows. I've seen too many people waste hours fighting PATH issues and weird compilation errors. Just use WSL and save yourself the headache.

The One Command That Actually Works

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

The --force flag is important - it overwrites any existing AVM install. Without it, you might end up with a broken installation that fails silently.

This downloads the AVM source, compiles it (takes 1-2 minutes), and installs the binary to ~/.cargo/bin/. If that directory isn't in your PATH, add it to your .bashrc or .zshrc:

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

Actually Using AVM (The Commands You'll Run 100 Times)

Install Anchor versions:

## Get the latest version (usually what you want)
avm install latest

## Install a specific version for compatibility
avm install 0.31.1

## Install from a specific commit for verifiable builds
avm install 0.31.0-d1ca820

Each version is ~100-200MB, so don't go crazy installing every version that ever existed.

Switch between versions:

## Use latest for new projects
avm use latest

## Switch to specific version for old projects
avm use 0.31.1

## Check what's currently active
anchor --version

See what you have installed:

## List all installed versions
avm list

## Update AVM itself when new features come out
cargo install --git https://github.com/coral-xyz/anchor avm --force

Things That Will Break (And How to Fix Them)

"Command not found: avm"

Your PATH is missing ~/.cargo/bin. Add it to your shell config and restart your terminal.

"Command not found: anchor" after installing

You installed a version but didn't activate it. Run avm use latest or whatever version you installed.

Multiple anchor installations fighting each other

If you had Anchor installed via npm before using AVM, uninstall it first:

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

Compilation fails during AVM install

Your Rust version is probably ancient. Update it:

rustup update stable

For more help with Rust issues, check Stack Overflow or update your Rust version first.

Windows Users: Just Use WSL

Windows support exists as of 2025, but every Windows user I know who tries native installation ends up switching to WSL anyway. The Solana ecosystem assumes a Unix-like environment, and fighting that assumption isn't worth your time.

Install WSL, install Rust inside WSL, then install AVM inside WSL. Your future self will thank you.

CI/CD Integration

In your build scripts, pin the exact version:

avm install 0.31.1
avm use 0.31.1
anchor build

Don't use avm install latest in CI unless you enjoy builds that randomly break when new Anchor versions come out.

If you're building anything that handles real money (which is most Solana programs), you need verifiable builds. Without this, users have to trust that you didn't backdoor their funds. That's not happening in 2025.

Why Verifiable Builds Matter

In traditional software, you can trust developers. In DeFi, trusting developers is how you lose millions of dollars. Verifiable builds let anyone rebuild your program and verify it matches what's on-chain.

AVM makes this possible by letting you install exact commit hashes, not just version tags:

## Install from the exact commit used for the deployment
avm install 0.31.0-d1ca820
avm use 0.31.0-d1ca820
anchor build --verifiable

The --verifiable flag ensures the build is reproducible. Different machines should produce identical bytecode, which users can verify against your deployment.

Team Workflow That Actually Works

Here's how teams use AVM without constantly breaking each other's environments:

Document the version in your README:

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

Add version checks to your build scripts:

#!/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

anchor build

This prevents the classic "it works on my machine" problems when team members use different Anchor versions.

Managing Multiple Projects

The reality: you'll have 3-4 Solana projects in different stages, each requiring different Anchor versions because the ecosystem moves fast and breaks things.

## Old project stuck on 0.29.0 because updating breaks everything
cd legacy-project
avm use 0.29.0
anchor build

## New project using latest features
cd new-hotness
avm use latest
anchor build

## Production project using specific commit for verifiable builds
cd production-app
avm use 0.31.0-d1ca820
anchor build --verifiable

AVM doesn't auto-switch like nvm does for Node.js - you have to remember to switch manually. This is actually good because accidentally building with the wrong version can be catastrophic.

Your SSD Will Fill Up Fast

Each Anchor version is 200MB. If you install 10 versions, that's 2GB. AVM doesn't have a built-in cleanup command yet, so you manually delete versions from `/.avm/` when you don't need them anymore.

## See what's taking up space
du -sh ~/.avm/*

## Remove old versions manually
rm -rf ~/.avm/0.28.0

Pro tip: Keep the last 3-4 versions and delete the rest unless you have specific reasons to keep older ones.

Common Fuck-Ups and Fixes

Building with the wrong version

Symptom: Mysterious compilation errors or different behavior than expected.
Fix: Always check anchor --version before building. Make it a habit.

PATH conflicts with old installations

Symptom: anchor --version shows a different version than avm list indicates is active.
Fix: Uninstall all non-AVM Anchor installations:

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

CI builds not reproducible

Symptom: CI produces different artifacts than local builds.
Fix: Pin the exact AVM version and Anchor version in CI:

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

Windows weirdness

Symptom: Everything breaks in subtle ways on Windows.
Fix: Use WSL. Seriously, just use WSL. Native Windows support exists but it's not worth the pain.

CI/CD Integration That Doesn't Break

In production CI/CD, use exact versions, not latest:

## GitHub Actions example
- 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: Verify version
  run: anchor --version

- name: Build verifiable
  run: anchor build --verifiable

Never use avm install latest in CI unless you want random build failures when new Anchor versions drop.