1---
2title: Version Compatibility Matrix
3description: Reference table for matching Anchor, Solana CLI, Rust, and Node.js versions to avoid toolchain conflicts.
4---
5 
6# Solana Version Compatibility Matrix
7 
8## Master Compatibility Table
9 
10| Anchor Version | Release Date | Solana CLI | Rust Version | Platform Tools | GLIBC Req | Node.js | Key Notes |
11|---|---|---|---|---|---|---|---|
12| **1.0.x** | — | 3.x | 1.79–1.85+ (stable) | v1.52 | ≥2.39 | ≥17 | TS pkg → `@anchor-lang/core`; `anchor test` defaults to surfpool; IDL in Program Metadata; no `solana` CLI shell-out; all `solana-*` deps must be `^3`; `solana-program` removed as project dep; `solana-signer` replaces `solana-sdk` for signing |
13| **0.32.x** | Oct 2025 | 2.1.x+ | 1.79–1.85+ (stable) | v1.50+ | ≥2.39 | ≥17 | Replaces `solana-program` with smaller crates; IDL builds on stable Rust; removes Solang |
14| **0.31.1** | Apr 2025 | 2.0.x–2.1.x | 1.79–1.83 | v1.47+ | ≥2.39 ⚠️ | ≥17 | New Docker image `solanafoundation/anchor`; published under solana-foundation org. **Tested: binary requires GLIBC 2.39, not 2.38** |
15| **0.31.0** | Mar 2025 | 2.0.x–2.1.x | 1.79–1.83 | v1.47+ | ≥2.39 ⚠️ | ≥17 | Solana v2 upgrade; dynamic discriminators; `LazyAccount`; `declare_program!` improvements. **Pre-built binary needs GLIBC 2.39** |
16| **0.30.1** | Jun 2024 | 1.18.x (rec: 1.18.8+) | 1.75–1.79 | v1.43 | ≥2.31 | ≥16 | `declare_program!` macro; legacy IDL conversion; `RUSTUP_TOOLCHAIN` override |
17| **0.30.0** | Apr 2024 | 1.18.x (rec: 1.18.8) | 1.75–1.79 | v1.43 | ≥2.31 | ≥16 | New IDL spec; token extensions; `cargo build-sbf` default; `idl-build` feature required |
18| **0.29.0** | Oct 2023 | 1.16.x–1.17.x | 1.68–1.75 | v1.37–v1.41 | ≥2.28 | ≥16 | Account reference changes; `idl build` compilation method; `.anchorversion` file |
19 
20## Solana CLI Version Mapping
21 
22| Solana CLI | Agave Version | Era | solana-program Crate | Platform Tools | Status |
23|---|---|---|---|---|---|
24| **3.1.x** | v3.1.x | Jan 2026 | N/A (validator only) | v1.52 | Edge/Beta |
25| **3.0.x** | v3.0.x | Late 2025 | N/A (validator only) | v1.52 | Stable (mainnet) |
26| **2.1.x** | v2.1.x | Mid 2025 | 2.x | v1.47–v1.51 | Stable |
27| **2.0.x** | v2.0.x | Early 2025 | 2.x | v1.44–v1.47 | Legacy |
28| **1.18.x** | N/A (pre-Anza) | 2024 | 1.18.x | v1.43 | Legacy |
29| **1.17.x** | N/A | 2023 | 1.17.x | v1.37–v1.41 | Deprecated |
30| **1.16.x** | N/A | 2023 | 1.16.x | v1.35–v1.37 | Deprecated |
31 
32### Important: Solana CLI v3.x
33As 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.
34 
35## Platform Tools → Rust Toolchain Mapping
36 
37| Platform Tools | Bundled Rust | Bundled Cargo | LLVM/Clang | Target Triple | Notes |
38|---|---|---|---|---|---|
39| **v1.52** | ~1.85 (solana fork) | ~1.85 | Clang 20 | `sbpf-solana-solana` | Latest; used by Solana CLI 3.x |
40| **v1.51** | ~1.84 (solana fork) | ~1.84 | Clang 19 | `sbpf-solana-solana` | |
41| **v1.50** | ~1.83 (solana fork) | ~1.83 | Clang 19 | `sbpf-solana-solana` | |
42| **v1.49** | ~1.82 (solana fork) | ~1.82 | Clang 18 | `sbpf-solana-solana` | |
43| **v1.48** | rustc 1.84.1-dev | cargo 1.84.0 | Clang 19 | `sbpf-solana-solana` | **Verified.** Used by Solana CLI 2.2.16. ⚠️ Cargo does NOT support `edition2024` |
44| **v1.47** | ~1.80 (solana fork) | ~1.80 | Clang 17 | `sbpf-solana-solana` | Used by Anchor 0.31.x |
45| **v1.46** | ~1.79 (solana fork) | ~1.79 | Clang 17 | `sbf-solana-solana` | |
46| **v1.45** | ~1.79 (solana fork) | ~1.79 | Clang 17 | `sbf-solana-solana` | |
47| **v1.44** | ~1.78 (solana fork) | ~1.78 | Clang 16 | `sbf-solana-solana` | |
48| **v1.43** | ~1.75 (solana fork) | ~1.75 | Clang 16 | `sbf-solana-solana` | Used by Anchor 0.30.x/Solana 1.18.x. ❌ Incompatible with CLI 2.2.16 (`sbpf-solana-solana` target not found) |
49 
50**Note:** Platform Tools ship a **forked** Rust compiler from [anza-xyz/rust](https://github.com/anza-xyz/rust). The version numbers approximate the upstream Rust equivalent. The forked compiler includes SBF/SBPF target support.
51 
52**⚠️ 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](./common-errors.md#edition2024-crate-incompatibility-cargo-1840) for full details and fix scripts.
53 
54## GLIBC Requirements by OS
55 
56| OS / Distro | GLIBC Version | Compatible Anchor |
57|---|---|---|
58| **Ubuntu 24.04 (Noble)** | 2.39 | All (0.29–v1+) |
59| **Ubuntu 22.04 (Jammy)** | 2.35 | 0.29–0.30.x only (build 0.31+ from source) |
60| **Ubuntu 20.04 (Focal)** | 2.31 | 0.29–0.30.x only (build 0.31+ from source) |
61| **Debian 12 (Bookworm)** | 2.36 | 0.29–0.30.x only ⚠️ **Tested: 0.31.1 and 0.32.1 pre-built binaries fail.** Build from source works for Anchor CLI, but `litesvm` 0.5.0 native binary also needs GLIBC 2.38+ |
62| **Debian 13 (Trixie)** | 2.40 | All |
63| **Fedora 39+** | ≥2.38 | All |
64| **Arch Linux (rolling)** | Latest | All |
65| **macOS 14+ (Sonoma)** | N/A (no GLIBC) | All |
66| **macOS 12-13** | N/A | All |
67| **Windows WSL2 (Ubuntu)** | Depends on distro | See Ubuntu version |
68 
69### Why GLIBC matters
70Anchor 0.31+ and 0.32+ binaries are compiled against newer GLIBC. If your system's GLIBC is too old, you'll get:
71```
72anchor: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found
73```
74 
75**Solutions:**
761. Upgrade your OS (recommended)
772. Build Anchor from source: `cargo install --git https://github.com/solana-foundation/anchor --tag v1.0.0 anchor-cli` (replace tag with desired version)
783. Use Docker (see install-guide.md)
79 
80## Anchor ↔ Solana Crate Versions
81 
82| Anchor | anchor-lang Crate | Project-level solana-* | Notes |
83|---|---|---|---|
84| **1.0.x** | 1.0.x | `^3` (granular crates) | `solana-program` removed from project deps; use `solana-signer` instead of `solana-sdk` for signing; all `solana-*` must be `^3` |
85| **0.32.x** | 0.32.x | `2` (still `solana-program` or granular v2) | anchor-lang internals use granular crates; `solana-program` still valid in user Cargo.toml |
86| **0.31.x** | 0.31.x | 2.x | Upgraded to Solana v2 crate ecosystem |
87| **0.30.x** | 0.30.x | 1.18.x | Last version using Solana v1 crates |
88| **0.29.x** | 0.29.x | 1.16.x–1.17.x | |
89 
90### Solana Granular Crate Ecosystem (Anchor 0.31+)
91Anchor 0.31+ uses the Solana v2+ crate structure. The monolithic `solana-program` crate is being split into smaller crates:
92- `solana-pubkey` / `solana-address`
93- `solana-instruction`
94- `solana-account-info`
95- `solana-msg`
96- `solana-invoke`
97- `solana-entrypoint`
98- `solana-signer` (use instead of `solana-sdk` in v1+)
99- etc.
100 
101Anchor 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.
102 
103## Anchor CLI ↔ anchor-lang Crate Compatibility
104 
105The 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:
106 
107```toml
108# Cargo.toml (Anchor v1)
109[dependencies]
110anchor-lang = "1.0.0"
111 
112# Must match CLI:
113# anchor --version → anchor-cli 1.0.0
114```
115 
116```toml
117# Cargo.toml (Anchor 0.32.x)
118[dependencies]
119anchor-lang = "0.32.1"
120 
121# anchor --version → anchor-cli 0.32.1
122```
123 
124## SPL Token Crate Versions
125 
126| Anchor | anchor-spl | spl-token | spl-token-2022 | spl-associated-token-account |
127|---|---|---|---|---|
128| **1.0.x** | 1.0.x | Latest compatible | Latest compatible | Latest compatible |
129| **0.32.x** | 0.32.x | Latest compatible | Latest compatible | Latest compatible |
130| **0.31.x** | 0.31.x | 6.x | 5.x | 4.x |
131| **0.30.x** | 0.30.x | 4.x–6.x | 3.x–4.x | 3.x |
132| **0.29.x** | 0.29.x | 4.x | 1.x–3.x | 2.x–3.x |
133 
134## Node.js / TypeScript Requirements
135 
136| Anchor | TS Package | Node.js | TypeScript | Notes |
137|---|---|---|---|---|
138| **1.0.x** | `@anchor-lang/core ^1.0.0` | ≥17 | 5.x | Renamed from `@coral-xyz/anchor`. IDL types now at root of `@anchor-lang/core` (was `@coral-xyz/anchor/dist/cjs/idl`) |
139| **0.32.x** | `@coral-xyz/anchor ^0.32.x` | ≥17 | 5.x | |
140| **0.31.x** | `@coral-xyz/anchor ^0.31.x` | ≥17 | 5.x | |
141| **0.30.x** | `@coral-xyz/anchor ^0.30.x` | ≥16 | 4.x–5.x | |
142| **0.29.x** | `@coral-xyz/anchor ^0.29.x` | ≥16 | 4.x | |
143 
144### Anchor v1 TypeScript Package Rename
145 
146The npm package moved from `@coral-xyz/anchor` to `@anchor-lang/core`. Update `package.json` and all imports:
147 
148```bash
149# Find all occurrences to update
150grep -r "@coral-xyz" --include="*.ts" --include="*.js" --include="package.json" .
151grep -r "dist/cjs/idl" --include="*.ts" --include="*.js" .
152```
153 
154```typescript
155// Before (0.32.x)
156import * as anchor from "@coral-xyz/anchor";
157import { Program, AnchorProvider, BN } from "@coral-xyz/anchor";
158import { Idl } from "@coral-xyz/anchor/dist/cjs/idl";
159 
160// After (v1)
161import * as anchor from "@anchor-lang/core";
162import { Program, AnchorProvider, BN } from "@anchor-lang/core";
163import { Idl } from "@anchor-lang/core";
164```
165 
166IDL management now uses `anchor idl init` / `anchor idl upgrade` (CLI) or `@solana-program/program-metadata` (npm) — see [migrating-v0.32-to-v1.md](./anchor/migrating-v0.32-to-v1.md#5-close-legacy-idl-accounts-and-re-publish-deploy).
167 
168## Known Working Combinations (Tested)
169 
170### 🟢 Anchor v1 (Recommended for new projects)
171```
172Anchor CLI: 1.0.0
173anchor-lang: 1.0.0
174anchor-spl: 1.0.0
175solana-* crates: ^3
176litesvm (dev): 0.8.2  (or 0.9.1 if solana-hash 4.0 / solana-vote-interface 5.0)
177anchor-litesvm (dev): 0.3
178TS: @anchor-lang/core ^1.0.0
179Solana CLI: 3.x
180Platform Tools: v1.52
181Rust: 1.79–1.85+
182Node.js: 20.x LTS
183OS: Ubuntu 24.04+ (GLIBC ≥2.39) or macOS 14+
184Test runner: surfpool (default in anchor test)
185```
186 
187### 🟢 Modern (Recommended for existing 0.32 projects — Jan 2026)
188```
189Anchor CLI: 0.31.1
190Solana CLI: 2.1.7 (stable)
191Rust: 1.83.0
192Platform Tools: v1.50
193Node.js: 20.x LTS
194OS: Ubuntu 24.04 or macOS 14+
195```
196 
197### 🟢 Latest 0.32.x (Cutting edge pre-v1)
198```
199Anchor CLI: 0.32.1
200Solana CLI: 2.1.7+
201Rust: 1.84.0+
202Platform Tools: v1.52
203Node.js: 20.x LTS
204OS: Ubuntu 24.04+ (GLIBC ≥2.39) or macOS 14+
205```
206 
207### 🟡 Legacy Compatible (For older systems)
208```
209Anchor CLI: 0.30.1
210Solana CLI: 1.18.26
211Rust: 1.79.0
212Platform Tools: v1.43
213Node.js: 18.x LTS
214OS: Ubuntu 20.04+ or macOS 12+
215```
216 
217### 🟡 Transitional (Upgrading from 0.30 → 0.31)
218```
219Anchor CLI: 0.31.0
220Solana CLI: 2.0.x
221Rust: 1.79.0
222Platform Tools: v1.47
223Node.js: 20.x LTS
224OS: Ubuntu 24.04 or macOS 14+
225```
226 
227## Testing Tools: LiteSVM / Bankrun Compatibility
228 
229### LiteSVM Rust Crate — Version Selection
230 
231Use the row that matches your workspace's resolved `solana-*` granular crate versions:
232 
233| litesvm (Rust) | solana-* era | Key markers | anchor-litesvm |
234|---|---|---|---|
235| **0.8.2** | `~3.0` | `solana-hash ~3.0`, `solana-vote-interface 4.0`, `solana-system-interface 2.0` | `0.3` (requires `anchor-lang ^1.0.0`, `litesvm ^0.8.2`) |
236| **0.9.1** | `~3.1`–`~3.3` | `solana-hash 4.0`, `solana-vote-interface 5.0`, `solana-system-interface 3.0` | TBD — `anchor-litesvm 0.3` declared `litesvm ^0.8.2`; check for a newer release |
237| **>0.10.0** | `3.3+` | follow latest releases | follow litesvm/anchor-litesvm release |
238 
239**Diagnostic:** run `cargo tree -d` — duplicate `solana-*` minor versions in the tree means the selected `litesvm` version is mismatched.
240 
241### LiteSVM npm Package (TypeScript tests)
242 
243| Tool | npm Package | GLIBC Req | Node.js | Notes |
244|---|---|---|---|---|
245| **LiteSVM 0.5.0** | `litesvm` | ≥2.38 ⚠️ | ≥18 | **Tested: native binary (`litesvm.linux-x64-gnu.node`) fails on Debian 12 (GLIBC 2.36) with `undefined symbol: __isoc23_strtol`**. Works on Ubuntu 24.04+, macOS. |
246| **LiteSVM 0.3.x** | `litesvm` | ≥2.31 | ≥16 | Older API, may work on older systems |
247| **solana-bankrun** | `solana-bankrun` | ≥2.28 | ≥16 | Legacy — being replaced by LiteSVM |
248| **anchor-bankrun** | `anchor-bankrun` | ≥2.28 | ≥16 | Legacy Anchor wrapper for bankrun |
249| **anchor-litesvm** | `anchor-litesvm` | Same as litesvm | ≥18 | Anchor wrapper for LiteSVM |
250 
251### LiteSVM on Older Systems
252If `litesvm` 0.5.0 fails with GLIBC errors:
2531. **Upgrade OS** to Ubuntu 24.04+ (recommended)
2542. **Use Docker**: `FROM ubuntu:24.04` base image
2553. **Fall back to `solana-bankrun`** temporarily
2564. **Build litesvm from source** (requires Rust + napi-rs toolchain)
257 
258### Verified Test Environment (Jan 2026)
259```
260✅ Works: Anchor CLI 0.30.1 (built from source) + Solana CLI 2.2.16 + Rust 1.93.0 + Debian 12
261❌ Fails: litesvm 0.5.0 native binary on Debian 12 (GLIBC 2.36)
262❌ Fails: Anchor 0.31.1/0.32.1 pre-built binaries on Debian 12 (GLIBC 2.36)
263✅ Works: cargo build-sbf (Solana 2.2.16, platform-tools v1.48) on Debian 12
264✅ Works: Anchor 0.30.1 built from source with Rust 1.93.0 on Debian 12
265```
266