> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/solana-foundation/anchor/llms.txt
> Use this file to discover all available pages before exploring further.

# anchor upgrade

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

<Warning>
  This command is deprecated since version 0.32.0. Use `anchor program upgrade` instead for more control and features.
</Warning>

## Overview

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

## Command Syntax

```bash theme={null}
anchor upgrade --program-id <PROGRAM_ID> <PROGRAM_FILEPATH> [OPTIONS] [-- <SOLANA_ARGS>...]
```

## Migration

Instead of:

```bash theme={null}
anchor upgrade --program-id <PROGRAM_ID> <FILEPATH>
```

Use:

```bash theme={null}
anchor program upgrade <PROGRAM_ID> --program-filepath <FILEPATH>
```

See the [Program Commands](/cli/deploy) documentation for the full feature set.

## Arguments

<ParamField path="program_id" type="pubkey" required>
  The program ID to upgrade
</ParamField>

<ParamField path="program_filepath" type="string" required>
  Filepath to the new program binary (e.g., `target/deploy/my_program.so`)
</ParamField>

## Options

<ParamField path="--max-retries" type="number" default="0">
  Maximum number of times to retry on failure
</ParamField>

<ParamField path="solana_args" type="string">
  Arguments to pass to the underlying `solana program deploy` command
</ParamField>

## Examples

### Basic Upgrade

```bash theme={null}
anchor upgrade --program-id Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS target/deploy/my_program.so
```

**Output:**

```
Upgrade authority: 3Z9vL1zjN6qyAFHhHQdWYRTFAcy69pJydkZmSFBKHg1R
Program Id: Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS

Upgrade successful
```

### Upgrade with Retries

```bash theme={null}
anchor upgrade --program-id Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS target/deploy/my_program.so --max-retries 3
```

### Upgrade Verifiable Build

```bash theme={null}
anchor build --verifiable
anchor upgrade --program-id Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS target/verifiable/my_program.so
```

### Pass Solana CLI Arguments

```bash theme={null}
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:

```bash theme={null}
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:

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

Override with:

```bash theme={null}
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

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

<Warning>
  The deprecation warning will be shown each time you run `anchor upgrade`. Migrate to `anchor program upgrade` for continued support.
</Warning>

<Info>
  The program's data account is preserved during an upgrade, so program state is maintained.
</Info>

<Tip>
  Build with `--verifiable` before upgrading to allow others to verify your upgrade matches the on-chain bytecode.
</Tip>

## See Also

* [anchor program upgrade](/cli/deploy) - Recommended replacement
* [anchor program set-upgrade-authority](/cli/deploy) - Change upgrade authority
* [anchor build --verifiable](/cli/build) - Create verifiable builds