Deploying Programs
Deploy compiled sBPF programs with solana program deploy, manage buffer accounts, and control upgrade authority from the CLI.
Recipe
Quick-reference recipe card - copy-paste ready.
cargo build-sbf
solana program deploy target/deploy/my_program.so
solana program show <PROGRAM_ID>
solana program set-upgrade-authority <PROGRAM_ID> --new-upgrade-authority <AUTH>When to reach for this:
- First deploy of an Anchor or native program to devnet/mainnet.
- Upgrading an existing program with a new
.soartifact. - Transferring upgrade authority to a multisig or DAO.
- Writing the program ID to
Anchor.toml/declare_id!after keygen.
Working Example
cd my_anchor_program
anchor build
# Artifact: target/deploy/my_anchor_program.so
solana config set --url devnet
solana airdrop 2
# Deploy with explicit program keypair (first deploy)
solana program deploy \
target/deploy/my_anchor_program.so \
--program-id target/deploy/my_anchor_program-keypair.json
PROGRAM_ID=$(solana-keygen pubkey target/deploy/my_anchor_program-keypair.json)
solana program show "$PROGRAM_ID"What this demonstrates:
cargo build-sbf/anchor buildproduces the.soconsumed by deploy.- Program keypair determines the on-chain program ID address.
program showconfirms loader, programdata account, and authority.
Deep Dive
How It Works
- Upgradeable BPF Loader v3 stores bytecode in a programdata account.
- Deploy transactions upload ELF in chunks to a buffer, then finalize into programdata.
- Upgrade authority pubkey can submit new upgrades or be set to
none(immutable). - Deploy costs lamports for rent-exempt programdata storage proportional to
.sosize.
Deploy Commands
| Command | Purpose |
|---|---|
program deploy | Upload and activate (or upgrade) bytecode |
program write-buffer | Upload to buffer only |
program deploy --buffer | Finalize from existing buffer |
program close | Reclaim lamports from buffer (authority required) |
program set-upgrade-authority | Transfer or revoke upgrade rights |
bash Notes
# Show deploy cost estimate
solana program deploy my_program.so --dry-run 2>&1 | grep -i cost
# Immutable program: revoke upgrade authority
solana program set-upgrade-authority <PROGRAM_ID> --finalGotchas
- Program ID mismatch -
declare_id!does not match deployed keypair. Fix: alignAnchor.tomlandlib.rswithsolana-keygen pubkeyof deploy keypair. - Insufficient SOL for rent - large programs need more lamports than a small airdrop. Fix: fund deployer with enough SOL for programdata rent plus fees.
- Deploying debug builds - unoptimized
.sowastes CU and rent. Fix:cargo build-sbf --release/anchor build. - Lost upgrade authority - setting authority to wrong key bricks upgrades. Fix: transfer to multisig deliberately; test on devnet first.
- Wrong cluster deploy - devnet program ID on mainnet config. Fix:
solana config getbefore every deploy.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
anchor deploy | Anchor workspace with scripted IDs | Raw native programs without Anchor |
solana program write-buffer + separate finalize | CI split upload and activation | Simple local dev loops |
solana-verify pipeline | Reproducible verified deploys | Quick throwaway devnet tests |
| Surfpool / local validator | Pre-mainnet simulation | Production release |
FAQs
Where is the .so file after anchor build?
target/deploy/<crate_name>.so plus matching -keypair.json for the program ID.
How much SOL does deploy cost?
Rent for programdata scales with bytecode size plus transaction fees. Run deploy on devnet and read the charged lamports in solana confirm -v.
Can I upgrade without redeploying the program ID?
Yes - submit a new .so to the same program ID while you hold upgrade authority.
What does --final do on set-upgrade-authority?
Removes upgrade authority permanently - the program becomes immutable.
What is a buffer account?
Temporary account holding uploaded ELF chunks before activation into programdata.
Can I deploy with a hardware wallet?
Possible with compatible signers, but most teams use a hot deploy key on devnet and multisig authority on mainnet.
Why did deploy fail with account already in use?
Often a partial buffer or concurrent deploy. Close stale buffers or wait for in-flight transactions to clear.
How do I verify the deployed binary hash?
solana program dump <ID> out.so and compare SHA256 with your build artifact, or use solana-verify for reproducible builds.
Does deploy work on localnet?
Yes - start solana-test-validator and deploy to http://127.0.0.1:8899.
Who pays deploy fees?
The fee payer on the deploy transaction - usually your configured CLI keypair.
Related
- Building Programs (cargo build-sbf) - compile before deploy
- Inspecting Accounts & Programs - post-deploy inspection
- Verifiable Builds (solana-verify) - reproducible artifacts
- solana-test-validator - local deploy target
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.