Building & Deploying
Build compiles your program to SBF and regenerates the IDL. Deploy uploads the .so to a cluster and updates the program ID mapping in Anchor.toml.
Recipe
anchor build
anchor deploy --provider.cluster devnet
anchor keys syncWhen to reach for this: You ship a new version or onboard a fresh program ID.
Working Example
# Verify toolchain
anchor --version # 0.32.1
solana --version # solana-cli 3.0.10
# Build SBF + IDL
anchor build
# Deploy to devnet (funded wallet)
anchor deploy --provider.cluster devnet
# Sync declare_id! and Anchor.toml from deployed keypair
anchor keys sync
# Confirm on-chain program
solana program show <PROGRAM_ID> --url devnet# programs/my_program/Cargo.toml
[dependencies]
anchor-lang = "0.32.1"
anchor-spl = "0.32.1"What this demonstrates:
target/deploy/*.sois the upgradeable program binary- IDL at
target/idl/<name>.jsondrives client codegen anchor keys syncalignsdeclare_id!with keypair- Cluster selection comes from
Anchor.tomlor CLI flags
Deep Dive
Build Pipeline
cargo build-sbfcompiles Rust to Solana BPF.- Anchor extracts account layouts and instructions into IDL JSON.
- TypeScript types can be generated from the IDL for tests.
Deploy Checklist
| Step | Command |
|---|---|
| Fund deployer | solana airdrop 2 (devnet) |
| Build | anchor build |
| Deploy | anchor deploy |
| Sync IDs | anchor keys sync |
| Verify | solana program show |
Gotchas
- Deploy without rebuild - Old .so uploaded.. Fix: Always
anchor buildbefore deploy. - IDL not committed - Clients drift from on-chain API.. Fix: Check in IDL or publish on-chain IDL.
- Wrong cluster provider - Program lands on unexpected network.. Fix: Set
[provider] clusterinAnchor.toml. - Insufficient SOL for deploy - Transaction fails mid-upload.. Fix: Fund deployer; deploy costs multiple SOL on mainnet.
- Skipping keys sync - declare_id mismatch errors.. Fix: Run sync after every new program keypair.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| solana program deploy | Non-Anchor workflows | You lose IDL generation step |
| CI verifiable builds | Audited releases | Local quick iteration |
| Surfpool for local only | No cluster spend | Final deploy still needs cluster |
FAQs
What Anchor version does this site use?
0.32.1 for anchor-lang, Anchor CLI, and examples in this section.
Do I need Solana CLI alongside Anchor?
Yes. Solana CLI 3.0.10 handles keypairs, airdrops, and solana program inspection.
Where does the IDL live after build?
target/idl/<program>.json in your workspace.
Can I mix UncheckedAccount with Signer?
Yes, but every unchecked field needs explicit constraints or handler checks.
How do I test without devnet?
Use anchor test with Surfpool 0.12.0 or LiteSVM 0.6.x in CI.
What is the 8-byte prefix on account data?
Anchor account discriminator; do not strip it when sizing space.
Should I commit generated IDL?
Yes, or publish on-chain IDL so clients have a canonical source.
How do I debug constraint failures?
Run with logs; Anchor prints constraint name and account index.
Does Anchor work on Agave 4.1.1?
Yes. This stack targets Agave validators with Solana CLI 3.0.10.
What should I read next in this section?
See sibling articles linked in Related for deeper build deploy topics.
Related
- The Anchor IDL - IDL format
- Project Structure - artifact paths
- Deployment Basics - cluster operations
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.