Polkadot SDK: What paritytech/polkadot-sdk Actually Ships

What the Polkadot SDK is for, and who it is not for

The README frames the repository as the place that "provides all the components needed to start building on the Polkadot network", described as a multi-chain platform where blockchains interoperate and share information. That sentence sets the audience: teams that want to run a chain, not teams that want to hold an asset.

The workspace layout confirms the scope. Top-level directories include substrate/, polkadot/, cumulus/, bridges/, templates/, umbrella/ and docker/. Substrate supplies the framework for building a blockchain node and runtime. Cumulus covers parachain-side components. The bridges/ tree holds relayers and pallets, including the snowbridge pallets for an Ethereum client and inbound and outbound queues. XCM, the cross-consensus messaging format, appears in the docs list of components alongside Substrate, FRAME and Cumulus.

So the project is a build dependency. If you are writing a runtime, defining pallets, running a collator, or wiring a bridge, this is the tree you pull from. If what you want is a wallet, a node to mine, or a price view, the repository has nothing to offer and the README does not pretend otherwise. Several of the questions Google returns for this name are about the network and the token, not the SDK; those are a different subject.

One workspace, three merged histories, and a quarterly release train

The README states plainly that the repository is "the amalgamation of 3 separate repositories that used to make up Polkadot SDK, namely Substrate, Polkadot and Cumulus", and links to a longer FAQ about the merge. That history explains the shape of the tree: crates that once lived independently now sit under one Cargo workspace rooted at Cargo.toml, which declares edition 2021, license GPL-3.0-only, and lists members across bridges/, cumulus/, polkadot/, substrate/ and templates/.

Releases follow a stated cadence: every three months as a Polkadot stableYYMM release, each supported for one year with patches. The recent tags match that pattern, with polkadot-stable2609-rc2 and polkadot-stable2609-rc1 as release candidates and polkadot-stable2606-2 as a patch on the previous stable line. The README points to the Release Registry for upcoming versions and to docs/RELEASE.md for more detail.

There is a deliberate split worth understanding before you start. The README says this repository provides the SDK pieces needed to build Polkadot and its parachains, but that "the actual Polkadot runtime lives in the fellowship/runtimes repository". If you are looking for the runtime that governs the network itself, you are in the wrong repository. The SDK is the toolkit; the fellowship repository holds the runtime built with it.

Installing the Polkadot SDK and running the getting-started script

The README offers a quickstart for an example node. It is a shell script fetched over HTTPS and piped into bash, which means you are executing remote code and should read it before running it in any environment you care about.

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/scripts/getting-started.sh | bash

The script lives at scripts/getting-started.sh in the repository. The README describes its purpose as getting an example node running quickly, and does not document what the script installs, which toolchain versions it expects, or how to undo it. Treat it as a convenience for a first look rather than a provisioning step.

For an actual build, the README does not inline the dependency list. It points to an external guide at docs.polkadot.com under develop/parachains/install-polkadot-sdk. That is where the required dependencies are described. Since the workspace is Rust with a Cargo.lock committed at the root, expect a normal cargo build once the external prerequisites are in place; the README itself does not print a cargo command for the whole workspace.

Two build targets have documented caveats. For WASM, the README says to set RUSTFLAGS="--cfg substrate_runtime". For PolkaVM, it says builds require a riscv32 or riscv64 target architecture and points to a CI example in .github/workflows/build-misc.yml. It also notes that the WASM builder handles configuration for full runtimes, while individual crates targeting no_std need care.

Keeping versions straight with psvm

Because the SDK spans many crates that must move together, hand-editing versions in a Cargo.toml is a losing game. The README recommends psvm, the Polkadot SDK Version Manager, described as a tool that manages and updates Polkadot SDK dependencies in any Cargo.toml file and updates them to their correct crates.io version.

The README does not give a full psvm command reference, only the link to the paritytech/psvm repository, so check that repository for the exact invocation and available flags before scripting it. What matters is the intent: you pick a stableYYMM release and let the tool align the crates, instead of resolving each one yourself. Given the one-year patch window on each stable release, this is also how you move between lines when a patch lands on the older one.

Where the Polkadot SDK gets in your way

The first limitation is size and build cost. This is a Cargo workspace containing substrate/, cumulus/, polkadot/, bridges/ and templates/ members, with a committed Cargo.lock. Compiling a meaningful subset is a long Rust build, and the README does not offer a trimmed profile for people who only want one crate.

The second is that the documentation is split across three places. The README sends you to docs.polkadot.com for the install guide, to paritytech.github.io/polkadot-sdk for rust-docs covering Substrate, FRAME, Cumulus and XCM, and to docs/RELEASE.md for release mechanics. Nothing in the README consolidates the build prerequisites; the getting-started script is the only self-contained path, and it is opaque about what it changes on your machine.

The third is the boundary between this repository and the fellowship runtimes. If your mental model is "clone this and you have Polkadot", the README corrects it: the actual Polkadot runtime lives elsewhere. You can build with the SDK without ever holding the network's runtime in this tree.

Finally, the licence is GPL-3.0-only per the workspace Cargo.toml. That is a copyleft licence, and the README does not discuss what it means for downstream distribution. Whether it fits your product is a question for your own counsel, not for this article.

Cosmos SDK is the comparison people actually make

The related searches pair this project with Cosmos SDK, and the difference is architectural rather than cosmetic. Cosmos SDK is a Go framework for building application-specific chains around Tendermint-style consensus, with IBC as the interoperability protocol. The Polkadot SDK is a Rust workspace where Substrate provides the node and runtime framework, Cumulus provides parachain components, and XCM handles cross-consensus messaging.

The practical consequence is where your chain lives. A Cosmos chain is typically sovereign by default and connects outward through IBC. A chain built with Cumulus is designed to run as a parachain on Polkadot, leasing a slot and inheriting shared security from the relay chain, which is a different trust and economics model. The repository also carries the bridges/ tree, including snowbridge pallets for an Ethereum client, so bridging to non-Polkadot chains is part of the SDK's surface rather than an external add-on.

Language is the other fork in the road. If your team writes Go, Cosmos SDK keeps you there. Choosing the Polkadot SDK means committing to Rust, to FRAME for runtime logic, and to the quarterly stableYYMM upgrade train described in the README.

Maintenance, releases and the upgrade bill

The repository is not archived, and its last push was on 2026-09-24, so it is being worked on. The release history supports that: polkadot-stable2609-rc2 was published on 2026-09-18, polkadot-stable2606-2 on 2026-09-15, and polkadot-stable2609-rc1 on 2026-09-04.

The upgrade cost is a stated policy, not a guess. A stable release arrives every three months and is supported for one year with patches. That gives you a predictable window, and it also means you cannot sit on a release indefinitely: at some point within a year you move to a supported line. psvm exists precisely to make that move mechanical across the SDK crates in your Cargo.toml.

On licensing, the workspace Cargo.toml declares GPL-3.0-only, while the repository metadata does not state a licence. The README does not address downstream obligations. GPL-3.0-only is copyleft, so if you plan to distribute a modified runtime, that is the clause to read first with your own legal input rather than an assumption that the SDK is permissively licensed.

Contributions are governed by docs/contributor/CONTRIBUTING.md and the Contributor Covenant in docs/contributor/CODE_OF_CONDUCT.md. Security reporting goes through docs/contributor/SECURITY.md. The README also notes that the project proposes on-chain tips on the Polkadot network for valuable contributions, and points to issues labeled mentor for newcomers.

Editorial conclusion

Adopt it if you are building a Substrate-based chain, a runtime, or bridge and XCM components, and you accept a large Rust workspace and a quarterly stable upgrade train. Do not adopt it if you want a wallet, a token, or a hosted API: the README describes an SDK for chain builders, and the wallet and investment questions in search data have no answer here. Verify first that the docs.polkadot.com install guide covers your toolchain, and that you can pin a stableYYMM release with psvm before writing runtime code.

Frequently asked questions

Official sources

1. Issues
2. paritytech/polkadot-sdk on GitHub
3. Project website
4. README
5. Releases