Version Compatibility Matrix

Master Compatibility Table

Solana CLI Version Mapping

Important: Solana CLI v3.x

As of Agave v3.0.0, Anza no longer publishes the agave-validator binary. Operators must build from source. The CLI tools (for program development) remain available via agave-install or the install script.

Platform Tools → Rust Toolchain Mapping

Note: Platform Tools ship a forked Rust compiler from anza-xyz/rust. The version numbers approximate the upstream Rust equivalent. The forked compiler includes SBF/SBPF target support.

⚠️ CRITICAL (Jan 2026): Platform-tools v1.48 bundles cargo 1.84.0 which does NOT support edition = "2024". Multiple crates now require it: blake3 ≥1.8.3, constant_time_eq ≥0.4.2, base64ct ≥1.8.3, indexmap ≥2.13.0. Pin to safe versions: blake3=1.8.2, constant_time_eq=0.3.1, base64ct=1.7.3, indexmap=2.11.4. Always commit Cargo.lock files. See common-errors.md for full details and fix scripts.

GLIBC Requirements by OS

Why GLIBC matters

Anchor 0.31+ and 0.32+ binaries are compiled against newer GLIBC. If your system's GLIBC is too old, you'll get:

anchor: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found

Solutions:

1. Upgrade your OS (recommended)
2. Build Anchor from source: cargo install --git https://github.com/solana-foundation/anchor --tag v1.0.0 anchor-cli (replace tag with desired version)
3. Use Docker (see install-guide.md)

Anchor ↔ Solana Crate Versions

Solana Granular Crate Ecosystem (Anchor 0.31+)

Anchor 0.31+ uses the Solana v2+ crate structure. The monolithic solana-program crate is being split into smaller crates:

• solana-pubkey / solana-address
• solana-instruction
• solana-account-info
• solana-msg
• solana-invoke
• solana-entrypoint
• solana-signer (use instead of solana-sdk in v1+)
• etc.

Anchor 0.32+ fully replaces solana-program in its own internals. Anchor v1.0+ goes further: user-facing Cargo.toml files must also drop solana-program and bump any remaining solana-* crates to ^3. The anchor build command warns on mismatched versions.

Anchor CLI ↔ anchor-lang Crate Compatibility

The Anchor CLI checks version compatibility with the anchor-lang crate used in your project. Mismatched versions will produce a warning. Always keep these in sync:

# Cargo.toml (Anchor v1)
[dependencies]
anchor-lang = "1.0.0"

# Must match CLI:
# anchor --version → anchor-cli 1.0.0

# Cargo.toml (Anchor 0.32.x)
[dependencies]
anchor-lang = "0.32.1"

# anchor --version → anchor-cli 0.32.1

SPL Token Crate Versions

Node.js / TypeScript Requirements

Anchor v1 TypeScript Package Rename

The npm package moved from @coral-xyz/anchor to @anchor-lang/core. Update package.json and all imports:

# Find all occurrences to update
grep -r "@coral-xyz" --include="*.ts" --include="*.js" --include="package.json" .
grep -r "dist/cjs/idl" --include="*.ts" --include="*.js" .

// Before (0.32.x)
import * as anchor from "@coral-xyz/anchor";
import { Program, AnchorProvider, BN } from "@coral-xyz/anchor";
import { Idl } from "@coral-xyz/anchor/dist/cjs/idl";

// After (v1)
import * as anchor from "@anchor-lang/core";
import { Program, AnchorProvider, BN } from "@anchor-lang/core";
import { Idl } from "@anchor-lang/core";

IDL management now uses anchor idl init / anchor idl upgrade (CLI) or @solana-program/program-metadata (npm) — see migrating-v0.32-to-v1.md.

Known Working Combinations (Tested)

🟢 Anchor v1 (Recommended for new projects)

Anchor CLI: 1.0.0
anchor-lang: 1.0.0
anchor-spl: 1.0.0
solana-* crates: ^3
litesvm (dev): 0.8.2  (or 0.9.1 if solana-hash 4.0 / solana-vote-interface 5.0)
anchor-litesvm (dev): 0.3
TS: @anchor-lang/core ^1.0.0
Solana CLI: 3.x
Platform Tools: v1.52
Rust: 1.79–1.85+
Node.js: 20.x LTS
OS: Ubuntu 24.04+ (GLIBC ≥2.39) or macOS 14+
Test runner: surfpool (default in anchor test)

🟢 Modern (Recommended for existing 0.32 projects — Jan 2026)

Anchor CLI: 0.31.1
Solana CLI: 2.1.7 (stable)
Rust: 1.83.0
Platform Tools: v1.50
Node.js: 20.x LTS
OS: Ubuntu 24.04 or macOS 14+

🟢 Latest 0.32.x (Cutting edge pre-v1)

Anchor CLI: 0.32.1
Solana CLI: 2.1.7+
Rust: 1.84.0+
Platform Tools: v1.52
Node.js: 20.x LTS
OS: Ubuntu 24.04+ (GLIBC ≥2.39) or macOS 14+

🟡 Legacy Compatible (For older systems)

Anchor CLI: 0.30.1
Solana CLI: 1.18.26
Rust: 1.79.0
Platform Tools: v1.43
Node.js: 18.x LTS
OS: Ubuntu 20.04+ or macOS 12+

🟡 Transitional (Upgrading from 0.30 → 0.31)

Anchor CLI: 0.31.0
Solana CLI: 2.0.x
Rust: 1.79.0
Platform Tools: v1.47
Node.js: 20.x LTS
OS: Ubuntu 24.04 or macOS 14+

Testing Tools: LiteSVM / Bankrun Compatibility

LiteSVM Rust Crate — Version Selection

Use the row that matches your workspace's resolved solana-* granular crate versions:

Diagnostic: run cargo tree -d — duplicate solana-* minor versions in the tree means the selected litesvm version is mismatched.

LiteSVM npm Package (TypeScript tests)

LiteSVM on Older Systems

If litesvm 0.5.0 fails with GLIBC errors:

1. Upgrade OS to Ubuntu 24.04+ (recommended)
2. Use Docker: FROM ubuntu:24.04 base image
3. Fall back to solana-bankrun temporarily
4. Build litesvm from source (requires Rust + napi-rs toolchain)

Verified Test Environment (Jan 2026)

✅ Works: Anchor CLI 0.30.1 (built from source) + Solana CLI 2.2.16 + Rust 1.93.0 + Debian 12
❌ Fails: litesvm 0.5.0 native binary on Debian 12 (GLIBC 2.36)
❌ Fails: Anchor 0.31.1/0.32.1 pre-built binaries on Debian 12 (GLIBC 2.36)
✅ Works: cargo build-sbf (Solana 2.2.16, platform-tools v1.48) on Debian 12
✅ Works: Anchor 0.30.1 built from source with Rust 1.93.0 on Debian 12