Deploying Programs

Q: Where is the .so file after anchor build?

target/deploy/.so plus matching -keypair.json for the program ID.

Q: Can I upgrade without redeploying the program ID?

Yes - submit a new .so to the same program ID while you hold upgrade authority.

Q: How do I verify the deployed binary hash?

solana program dump out.so and compare SHA256 with your build artifact, or use solana-verify for reproducible builds.

Q: Does deploy work on localnet?

Yes - start solana-test-validator and deploy to http://127.0.0.1:8899.

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 .so artifact.
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 build produces the .so consumed by deploy.
Program keypair determines the on-chain program ID address.
program show confirms 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 .so size.

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> --final

Gotchas

Program ID mismatch - declare_id! does not match deployed keypair. Fix: align Anchor.toml and lib.rs with solana-keygen pubkey of 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 .so wastes 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 get before 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.

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.

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 .so artifact.
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 build produces the .so consumed by deploy.
Program keypair determines the on-chain program ID address.
program show confirms 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 .so size.

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> --final

Gotchas

Program ID mismatch - declare_id! does not match deployed keypair. Fix: align Anchor.toml and lib.rs with solana-keygen pubkey of 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 .so wastes 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 get before 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.

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.

Deploying Programs

Search Documentation

Deploying Programs