> For the complete documentation index, see [llms.txt](https://learn.onpop.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learn.onpop.io/chains/guides/upgrade-polkadot-sdk.md).

# Upgrade Polkadot SDK dependencies

Use `pop upgrade` to update Polkadot SDK dependency versions in a chain project. It rewrites entries in your `Cargo.toml` using a known version mapping.

You can also run the command as `pop ug`. Use this command in a chain project that has a `Cargo.toml`. Network access is required to fetch available Polkadot SDK versions.

## Usage

```bash
pop upgrade [--path <PATH>] [--version <VERSION>]
```

### JSON mode

Use global `--json` for structured output in automation:

```bash
pop --json upgrade --path /path/to/project --version polkadot-stable2509-1
```

In JSON mode, `--version` is required because interactive version selection is disabled.

## Examples

```bash
# Upgrade the current project and select a version interactively
pop upgrade

# Upgrade a specific project directory
pop upgrade --path /path/to/project

# Upgrade a specific Cargo.toml
pop upgrade --path /path/to/project/Cargo.toml

# Upgrade to a specific Polkadot SDK tag
pop upgrade --version polkadot-stable2509-1
```

## How version selection works

If you omit `--version`, Pop fetches available Polkadot SDK release tags from GitHub and prompts you to select one. The prompt is filterable as you type.

If you pass `--version`, Pop skips the prompt and uses your value directly.

## Path resolution

* If `--path` points to a `Cargo.toml`, Pop uses it directly.
* If `--path` points to a directory, Pop appends `Cargo.toml`.
* If you omit `--path`, Pop uses the `Cargo.toml` in your current directory.

## Output and follow-up

After the update, Pop prints a warning that the upgrade may introduce compile errors and recommends running `pop build`. It also prints a success message with the version you selected.

## Errors and constraints

* Missing `Cargo.toml`: `Cargo.toml file not found at specified path`.
* Version mapping fetch failed: `Failed to get version mapping: <error>`.
* Dependency update failed: `Failed to update dependencies: <error>`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.onpop.io/chains/guides/upgrade-polkadot-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.