Anchor Version Manager (AVM)

Install and manage multiple versions of the Anchor CLI with AVM for version-specific development and verifiable builds.

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:

1. Check PATH configuration:

   echo $PATH | grep .avm
   

2. Ensure a version is selected:

   avm list
   avm use 0.32.1
   

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

1. Ensure Rust toolchain is up to date:

   rustup update
   

2. Install build dependencies (Linux):

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

3. 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

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

Resources

• AVM Source Code
• Anchor CLI Reference
• Verifiable Builds
• Anchor.toml Configuration