Skip to main content
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

Featureanchor 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

Build docs developers (and LLMs) love

Get started for freeTalk to us