anchor upgrade

Upgrade a deployed program (deprecated, use anchor program upgrade)

This command is deprecated since version 0.32.0. Use anchor program upgrade instead for more control and features.

Overview

The anchor upgrade command upgrades a single program on the Solana cluster. The configured wallet must be the upgrade authority.

Command Syntax

anchor upgrade --program-id <PROGRAM_ID> <PROGRAM_FILEPATH> [OPTIONS] [-- <SOLANA_ARGS>...]

Migration

Instead of:

anchor upgrade --program-id <PROGRAM_ID> <FILEPATH>

Use:

anchor program upgrade <PROGRAM_ID> --program-filepath <FILEPATH>

See the Program Commands documentation for the full feature set.

Arguments

program_id · pubkey · required

The program ID to upgrade

program_filepath · string · required

Filepath to the new program binary (e.g., target/deploy/my_program.so)

Options

--max-retries · number · default: "0"

Maximum number of times to retry on failure

solana_args · string

Arguments to pass to the underlying solana program deploy command

Examples

Basic Upgrade

anchor upgrade --program-id Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS target/deploy/my_program.so

Output:

Upgrade authority: 3Z9vL1zjN6qyAFHhHQdWYRTFAcy69pJydkZmSFBKHg1R
Program Id: Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS

Upgrade successful

Upgrade with Retries

anchor upgrade --program-id Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS target/deploy/my_program.so --max-retries 3

Upgrade Verifiable Build

anchor build --verifiable
anchor upgrade --program-id Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS target/verifiable/my_program.so

Pass Solana CLI Arguments

anchor upgrade --program-id Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS target/deploy/my_program.so -- --with-compute-unit-price 1000

Upgrade Process

1. Validates the upgrade authority has permission
2. Uploads the new program binary to a buffer account
3. Calls the upgrade instruction on the BPF Upgradeable Loader
4. Replaces the existing program with the new binary
5. Closes the buffer account and reclaims rent

Authority Requirements

The wallet specified in Anchor.toml or via the Solana CLI config must be the upgrade authority for the program. You can verify this with:

solana program show <PROGRAM_ID>

Output will show:

Program Id: Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS
Owner: BPFLoaderUpgradeab1e11111111111111111111111
ProgramData Address: 4Z9vL1zjN6qyAFHhHQdWYRTFAcy69pJydkZmSFBKHg1R
Authority: 3Z9vL1zjN6qyAFHhHQdWYRTFAcy69pJydkZmSFBKHg1R
...

Cluster Configuration

The upgrade cluster is determined by:

[provider]
cluster = "devnet"  # Or "localnet", "mainnet-beta", custom URL
wallet = "~/.config/solana/id.json"

Override with:

anchor upgrade --provider.cluster mainnet-beta --program-id <ID> <FILEPATH>

Failure Handling

If the upgrade fails:

1. Check your upgrade authority is correct
2. Ensure you have enough SOL for rent and fees
3. Verify the program binary is valid
4. Use --max-retries for network issues

Comparison with New Command

Feature	anchor upgrade (deprecated)	anchor program upgrade (new)
Basic upgrade	✓	✓
Max retries	✓	✓
Custom upgrade authority	✗	✓
Use existing buffer	✗	✓
Auto-discover from workspace	✗	✓
Program name support	✗	✓

Notes

Always test upgrades on devnet before upgrading on mainnet-beta. Program upgrades are immediate and irreversible.

The deprecation warning will be shown each time you run anchor upgrade. Migrate to anchor program upgrade for continued support.

The program’s data account is preserved during an upgrade, so program state is maintained.

Build with --verifiable before upgrading to allow others to verify your upgrade matches the on-chain bytecode.

See Also

• anchor program upgrade - Recommended replacement
• anchor program set-upgrade-authority - Change upgrade authority
• anchor build —verifiable - Create verifiable builds