Toolchain Overview
The Solana developer toolchain stacks Rust, Agave validator/CLI binaries, platform tools (cargo build-sbf), and Anchor into one reproducible build-and-deploy pipeline.
Recipe
Quick-reference recipe card - copy-paste ready.
rustc --version # 1.91.1
solana --version # solana-cli 3.0.10 (Agave 4.1.1)
anchor --version # 0.32.1
cargo build-sbf --versionWhen to reach for this:
- Onboarding a new engineer to the expected tool versions.
- Debugging "works on my machine" compile or deploy failures.
- Choosing between native Rust programs vs Anchor framework workflows.
- Auditing whether CI matches local developer laptops.
Working Example
# Core versions for this guide's pinned stack
rustc --version
cargo --version
solana --version
agave-install --version
anchor --version
avm --version
# Typical program workflow
anchor init my_program
cd my_program
anchor build
solana program deploy target/deploy/my_program.soWhat this demonstrates:
- Rust compiles on-chain programs to sBPF ELF via
cargo build-sbf. - Agave ships
solana,solana-keygen,spl-token, and validator binaries. - Anchor wraps program structure, IDL generation, and test harnesses.
Deep Dive
How It Works
- Rust 1.91.1 is the language toolchain for programs and many off-chain services.
- Agave 4.1.1 is the validator client; Solana CLI 3.0.10 is the operator-facing binary bundle.
- cargo build-sbf cross-compiles to Solana's sBPF target with platform-specific sysroots.
- Anchor 0.32.1 provides macros, account validation, IDL, and TypeScript client codegen.
Toolchain Map
| Tool | Role | Pin (this site) |
|---|---|---|
rustc / cargo | Language build | 1.91.1 |
cargo build-sbf | sBPF compile | via Agave platform tools |
solana CLI | RPC ops, deploy | 3.0.10 |
agave-install | Version switching | 4.1.1 channel |
anchor / avm | Framework + version mgr | 0.32.1 |
@solana/kit | TS RPC client | 7.0.0 |
bash Notes
# Verify platform tools on PATH
which cargo-build-sbf
ls "$(dirname $(which solana))"/cargo-build-sbfGotchas
- Mixing Solana 1.x and Agave 4.x - legacy install scripts pull old toolchains. Fix: use
agave-install4.1.1 channel exclusively. - Global Anchor drift - multiple projects need different Anchor versions. Fix:
avm use 0.32.1per repo withAnchor.toml. - Missing platform tools -
cargo build-sbfnot found after partial install. Fix: reinstall Agave bundle; check PATH. - Node client vs CLI confusion -
@solana/kitdoes not replacesolana program deploy. Fix: CLI for ops, kit for app reads/writes. - Rust nightly for programs - on-chain target expects stable toolchain. Fix: stay on stable 1.91.1 unless docs explicitly require nightly.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
Native pinocchio / solana-program | Maximum CU/size control | Rapid prototyping |
mucho scaffold CLI | Foundation templates | Minimal custom architecture |
create-solana-dapp | Full-stack Next.js + program | Backend-only services |
| LiteSVM / Mollusk tests | Fast unit tests without validator | Production deploy steps |
FAQs
What is Agave vs Solana Labs?
Agave is the Anza-maintained validator and CLI lineage continuing open-source Solana development. Commands remain solana-* branded.
Do I need Anchor?
No for native programs, yes for faster account validation, IDL, and client codegen in most product teams.
Where does cargo build-sbf come from?
Shipped with Agave platform tools installed alongside the CLI bundle.
What Node version for clients?
Use current LTS Node for @solana/kit 7.x projects; pin in .nvmrc per app repo.
Is the validator required for app devs?
App developers need CLI + kit; validators are for local solana-test-validator or operators running nodes.
How does Surfpool fit?
Surfpool 0.12.0 adds mainnet-fork local simulation - complementary to Agave test validator.
What is avm?
Anchor Version Manager - installs and selects Anchor CLI versions like nvm for Node.
Can I use Docker instead?
Yes for CI reproducibility - mount tool versions explicitly rather than latest images.
What ties anchor-lang crate version?
Match anchor-lang = "0.32.1" in Cargo.toml to CLI 0.32.1 per Anchor release notes.
How do I verify the full stack?
Run the version commands in the Recipe block in CI and fail builds on mismatch.
Related
- Version Management (agave-install / avm) - pin versions
- Building Programs (cargo build-sbf) - compile pipeline
- Editor & rust-analyzer Setup - IDE loop
- Solana CLI Basics - CLI configuration
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.