Anchor Version Manager (AVM)

Anchor Version Manager (AVM) is a command-line tool for managing multiple installations of the Anchor CLI. It allows you to easily switch between Anchor versions for different projects, which is essential for:

Working with projects that require specific Anchor versions
Creating verifiable builds that match deployed programs
Testing features across different Anchor releases
Maintaining legacy projects

Installation

Install AVM using Cargo:

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

Verify installation:

avm --version

Commands

avm install

Install a specific version of Anchor CLI.

avm install <VERSION_OR_COMMIT>

Install by Version:

# Install specific version
avm install 0.32.1

# Install latest release
avm install latest

Install by Commit:

# Version with commit hash
avm install 0.30.1-cfe82aa682138f7c6c58bf7a78f48f7d63e9e466

# Full commit hash
avm install cfe82aa682138f7c6c58bf7a78f48f7d63e9e466

# Short commit hash (minimum 7 characters)
avm install cfe82aa

Options:

--force - Force installation even if version exists
--from-source - Build from source instead of downloading prebuilt binaries
--verify - Also install solana-verify tool
--path <PATH> - Install from a local Anchor repository

Examples:

# Force reinstall a version
avm install 0.32.1 --force

# Build from source
avm install 0.32.1 --from-source

# Install with solana-verify
avm install 0.32.1 --verify

# Install from local path
avm install --path ~/projects/anchor

Prebuilt binaries are available for most releases. Use --from-source if you need a custom build or encounter binary compatibility issues.

avm use

Switch to a specific Anchor CLI version.

avm use <VERSION>

Examples:

# Use specific version
avm use 0.32.1

# Use latest installed version
avm use latest

The version must be installed before using it. Run avm install <VERSION> first.

avm list

List all installed Anchor CLI versions.

avm list

Alias:

avm ls

Example Output:

Installed versions:
* 0.32.1 (current)
  0.30.1
  0.29.0

The asterisk (*) indicates the currently active version.

avm uninstall

Remove an installed Anchor CLI version.

avm uninstall <VERSION>

Example:

avm uninstall 0.29.0

You cannot uninstall the currently active version. Switch to a different version with avm use first.

avm update

Update to the latest Anchor CLI release.

avm update

This is equivalent to:

avm install latest
avm use latest

avm completions

Generate shell completion scripts for AVM.

avm completions <SHELL>

Supported Shells:

bash
zsh
fish
powershell
elvish

Setup Examples: Bash:

avm completions bash > ~/.local/share/bash-completion/completions/avm

Zsh:

avm completions zsh > ~/.zsh/completion/_avm

Fish:

avm completions fish > ~/.config/fish/completions/avm.fish

Usage Patterns

Project-Specific Versions

Use different Anchor versions for different projects:

# Project A (uses Anchor 0.32.1)
cd ~/projects/project-a
avm use 0.32.1
anchor build

# Project B (uses Anchor 0.30.1)
cd ~/projects/project-b
avm use 0.30.1
anchor build

Anchor.toml Integration

Specify the required Anchor version in your project’s Anchor.toml:

Anchor.toml

[toolchain]
anchor_version = "0.32.1"
solana_version = "2.3.0"

Anchor CLI will automatically use the specified version if installed via AVM:

# Reads anchor_version from Anchor.toml
anchor build

If the required version isn’t installed:

# Install the version specified in Anchor.toml
avm install 0.32.1

Verifiable Builds

AVM is essential for creating verifiable builds that match deployed programs:

# Install the version used for the deployed program
avm install 0.32.1

# Use that version
avm use 0.32.1

# Build verifiably
anchor build --verifiable

# Verify against deployed program
anchor verify -p my_program <program-id>

Testing Multiple Versions

Test your program against different Anchor versions:

#!/bin/bash
# test-versions.sh

VERSIONS=("0.30.1" "0.31.0" "0.32.1")

for version in "${VERSIONS[@]}"; do
    echo "Testing with Anchor $version"
    avm use $version
    anchor test || echo "Tests failed on $version"
done

Installation Locations

AVM installs Anchor CLI versions to: Linux/macOS:

~/.avm/
├── bin/              # Current version symlinks
│   └── anchor -> ~/.avm/versions/0.32.1/bin/anchor
└── versions/         # Installed versions
    ├── 0.32.1/
    │   └── bin/
    │       └── anchor
    ├── 0.30.1/
    └── 0.29.0/

Windows:

%USERPROFILE%\.avm\versions\

PATH Configuration

AVM requires ~/.avm/bin in your PATH. Add to your shell configuration: Bash (~/.bashrc):

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

Zsh (~/.zshrc):

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

Fish (~/.config/fish/config.fish):

set -gx PATH $HOME/.avm/bin $PATH

Reload your shell:

source ~/.bashrc  # or ~/.zshrc

Troubleshooting

Version Not Found

Error:

Error: Version 0.32.1 not found

Solution:

avm install 0.32.1

Command Not Found

Error:

anchor: command not found

Solutions:

Check PATH configuration:
```
echo $PATH | grep .avm
```
Ensure a version is selected:
```
avm list
avm use 0.32.1
```

Reinstall AVM:

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

Build Failures

Error when using --from-source:

Error: Failed to build anchor-cli

Solutions:

Ensure Rust toolchain is up to date:
```
rustup update
```

Install build dependencies (Linux):

sudo apt-get install pkg-config libssl-dev libudev-dev

Try without --from-source:
```
avm install 0.32.1
```

Permission Denied

Error:

Permission denied (os error 13)

Solution: Ensure ~/.avm is writable:

chmod -R u+w ~/.avm

Advanced Usage

CI/CD Integration

GitHub Actions:

name: Build and Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install AVM
        run: cargo install --git https://github.com/coral-xyz/anchor avm --force
      
      - name: Install Anchor
        run: |
          avm install 0.32.1
          avm use 0.32.1
      
      - name: Build
        run: anchor build
      
      - name: Test
        run: anchor test

Docker Integration

FROM rust:latest

# Install AVM
RUN cargo install --git https://github.com/coral-xyz/anchor avm --force

# Install Anchor
RUN avm install 0.32.1 && avm use 0.32.1

# Add to PATH
ENV PATH="/root/.avm/bin:${PATH}"

WORKDIR /app
COPY . .

RUN anchor build

Best Practices

Specify Versions in Anchor.toml

Always document the required version:

[toolchain]
anchor_version = "0.32.1"

This helps collaborators use the correct version.

Use Prebuilt Binaries

Avoid --from-source unless necessary:

# Preferred
avm install 0.32.1

# Only when needed
avm install 0.32.1 --from-source

Prebuilt binaries are faster and more reliable.

Keep AVM Updated

Periodically update AVM itself:

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

Document Version Requirements

Include installation instructions in your README:

## Prerequisites

Install AVM: `cargo install --git https://github.com/coral-xyz/anchor avm --force`
Install Anchor: `avm install 0.32.1 && avm use 0.32.1`
Build: `anchor build`

Get Started

Core Concepts

Building Programs

Client Libraries

Testing

Token Extensions

Advanced

Anchor Version Manager (AVM)

Installation

Commands

avm install

avm use

avm list

avm uninstall

avm update

avm completions

Usage Patterns

Project-Specific Versions

Anchor.toml Integration

Verifiable Builds

Testing Multiple Versions

Installation Locations

PATH Configuration

Troubleshooting

Version Not Found

Command Not Found

Build Failures

Permission Denied

Advanced Usage

CI/CD Integration

Docker Integration

Best Practices

Resources

Build docs developers (and LLMs) love

Get Started

Core Concepts

Building Programs

Client Libraries

Testing

Token Extensions

Advanced

​Installation

​Commands

​avm install

​avm use

​avm list

​avm uninstall

​avm update

​avm completions

​Usage Patterns

​Project-Specific Versions

​Anchor.toml Integration

​Verifiable Builds

​Testing Multiple Versions

​Installation Locations

​PATH Configuration

​Troubleshooting

​Version Not Found

​Command Not Found

​Build Failures

​Permission Denied

​Advanced Usage

​CI/CD Integration

​Docker Integration

​Best Practices

​Resources

Build docs developers (and LLMs) love

Installation

Commands

avm install

avm use

avm list

avm uninstall

avm update

avm completions

Usage Patterns

Project-Specific Versions

Anchor.toml Integration

Verifiable Builds

Testing Multiple Versions

Installation Locations

PATH Configuration

Troubleshooting

Version Not Found

Command Not Found

Build Failures

Permission Denied

Advanced Usage

CI/CD Integration

Docker Integration

Best Practices

Resources