> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/solana-foundation/anchor/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```shell theme={null}
cargo install --git https://github.com/coral-xyz/anchor avm --force
```

Verify installation:

```shell theme={null}
avm --version
```

## Commands

### avm install

Install a specific version of Anchor CLI.

```shell theme={null}
avm install <VERSION_OR_COMMIT>
```

**Install by Version:**

```shell theme={null}
# Install specific version
avm install 0.32.1

# Install latest release
avm install latest
```

**Install by Commit:**

```shell theme={null}
# 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:**

```shell theme={null}
# 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
```

<Callout type="info">
  Prebuilt binaries are available for most releases. Use `--from-source` if you need a custom build or encounter binary compatibility issues.
</Callout>

### avm use

Switch to a specific Anchor CLI version.

```shell theme={null}
avm use <VERSION>
```

**Examples:**

```shell theme={null}
# Use specific version
avm use 0.32.1

# Use latest installed version
avm use latest
```

<Callout type="warning">
  The version must be installed before using it. Run `avm install <VERSION>` first.
</Callout>

### avm list

List all installed Anchor CLI versions.

```shell theme={null}
avm list
```

**Alias:**

```shell theme={null}
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.

```shell theme={null}
avm uninstall <VERSION>
```

**Example:**

```shell theme={null}
avm uninstall 0.29.0
```

<Callout type="warning">
  You cannot uninstall the currently active version. Switch to a different version with `avm use` first.
</Callout>

### avm update

Update to the latest Anchor CLI release.

```shell theme={null}
avm update
```

This is equivalent to:

```shell theme={null}
avm install latest
avm use latest
```

### avm completions

Generate shell completion scripts for AVM.

```shell theme={null}
avm completions <SHELL>
```

**Supported Shells:**

* `bash`
* `zsh`
* `fish`
* `powershell`
* `elvish`

**Setup Examples:**

**Bash:**

```shell theme={null}
avm completions bash > ~/.local/share/bash-completion/completions/avm
```

**Zsh:**

```shell theme={null}
avm completions zsh > ~/.zsh/completion/_avm
```

**Fish:**

```shell theme={null}
avm completions fish > ~/.config/fish/completions/avm.fish
```

## Usage Patterns

### Project-Specific Versions

Use different Anchor versions for different projects:

```shell theme={null}
# 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`:

```toml title="Anchor.toml" theme={null}
[toolchain]
anchor_version = "0.32.1"
solana_version = "2.3.0"
```

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

```shell theme={null}
# Reads anchor_version from Anchor.toml
anchor build
```

If the required version isn't installed:

```shell theme={null}
# 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:

```shell theme={null}
# 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:

```shell theme={null}
#!/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):**

```bash theme={null}
export PATH="$HOME/.avm/bin:$PATH"
```

**Zsh (\~/.zshrc):**

```zsh theme={null}
export PATH="$HOME/.avm/bin:$PATH"
```

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

```fish theme={null}
set -gx PATH $HOME/.avm/bin $PATH
```

Reload your shell:

```shell theme={null}
source ~/.bashrc  # or ~/.zshrc
```

## Troubleshooting

### Version Not Found

**Error:**

```
Error: Version 0.32.1 not found
```

**Solution:**

```shell theme={null}
avm install 0.32.1
```

### Command Not Found

**Error:**

```
anchor: command not found
```

**Solutions:**

1. Check PATH configuration:
   ```shell theme={null}
   echo $PATH | grep .avm
   ```

2. Ensure a version is selected:
   ```shell theme={null}
   avm list
   avm use 0.32.1
   ```

3. Reinstall AVM:
   ```shell theme={null}
   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:
   ```shell theme={null}
   rustup update
   ```

2. Install build dependencies (Linux):
   ```shell theme={null}
   sudo apt-get install pkg-config libssl-dev libudev-dev
   ```

3. Try without `--from-source`:
   ```shell theme={null}
   avm install 0.32.1
   ```

### Permission Denied

**Error:**

```
Permission denied (os error 13)
```

**Solution:**
Ensure `~/.avm` is writable:

```shell theme={null}
chmod -R u+w ~/.avm
```

## Advanced Usage

### CI/CD Integration

**GitHub Actions:**

```yaml theme={null}
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

```dockerfile theme={null}
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

<AccordionGroup>
  <Accordion title="Specify Versions in Anchor.toml">
    Always document the required version:

    ```toml theme={null}
    [toolchain]
    anchor_version = "0.32.1"
    ```

    This helps collaborators use the correct version.
  </Accordion>

  <Accordion title="Use Prebuilt Binaries">
    Avoid `--from-source` unless necessary:

    ```shell theme={null}
    # Preferred
    avm install 0.32.1

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

    Prebuilt binaries are faster and more reliable.
  </Accordion>

  <Accordion title="Keep AVM Updated">
    Periodically update AVM itself:

    ```shell theme={null}
    cargo install --git https://github.com/coral-xyz/anchor avm --force
    ```
  </Accordion>

  <Accordion title="Document Version Requirements">
    Include installation instructions in your README:

    ```markdown theme={null}
    ## 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`
    ```
  </Accordion>
</AccordionGroup>

## Resources

* [AVM Source Code](https://github.com/coral-xyz/anchor/tree/master/avm)
* [Anchor CLI Reference](/cli/init)
* [Verifiable Builds](/advanced/verifiable-builds)
* [Anchor.toml Configuration](/advanced/anchor-toml)