Pi Network enabled protocol upgrade 24.1 in May, requiring all node operators to complete the migration from v23.0 to v24.1 before the June 2 deadline; nodes that miss the deadline may be disconnected from the Pi mainnet, and will need to fully resync from scratch to rejoin the network.
v24.1 Upgrade Operation Guide: Three Confirmed Methods
Method 1 (primary method): For Docker users, update the image version in docker-compose.yml to: pinetwork/pi-node-docker:organization_mainnet-v1.0-p24.1.0, then run docker-compose up -d
Method 2: Restart the Pi Node application in Pi Desktop (Windows / macOS); the latest version will automatically trigger the upgrade.
Method 3: On a Linux Node CLI, run pi-node update-protocol, use watch pi-node status to monitor the status, and complete the process when it shows “Synchronized.”
The only reliable way to confirm the migration is complete: Compare the ingest_latest_ledger value on the node (the value on curl); when the two are roughly equal, it indicates the migration is finished. Important: During the migration process, this value will not update step by step; it only updates once, after the migration completes. The fact that the value does not change during the migration does not mean the migration failed.
Four Confirmed Key Operational Rules
（Source: Pi Network）
Upgrade in batches: Do not upgrade all nodes at the same time; proceed in stages. During the upgrade, shift traffic from nodes that are being upgraded to other nodes or backup nodes.
Do not start v25.1 or v26.0 on your own: These two versions have been marked “Do not start.” You must wait for the official start signal from the Pi core team.
June 2 is a hard cutoff date: The migration time must not exceed 5 minutes. The Pi core team recommends completing it as early as possible rather than waiting until the end.
Must confirm completion via the ledger endpoint: Do not assume migration is complete just by restarting the node; you must verify by comparing ingest_latest_ledger.
Common Questions
What is the design logic behind Pi Network’s v19→v26 upgrade sequence, and why is each step mandatory?
Pi Network’s upgrade sequence is a linear dependency design: each new version’s features are built on top of the previous version, so you cannot skip steps. This design ensures the entire network maintains a consistent protocol version at any time, preventing nodes running different versions from being unable to communicate effectively. The more nodes still running older versions in the network, the slower the full deployment of new-version functionality across the network becomes. Therefore, the mandatory cutoff dates are intended to ensure a rapid transition of the network to the next version. v23.0 is the most complex step in this sequence, as it upgrades both the operating system and the database at the same time; v24.1 advances on this basis by integrating the new versions of Stellar-Core and Horizon.
After upgrading the Pi mainnet protocol to v24.1, will smart contract and dApp functionality be activated?
No. The Pi core team has explicitly confirmed that the activation of smart contracts and decentralized applications (dApps) on the Pi mainnet has not been officially announced. Protocol 23.0 aligns Pi with Stellar Core v23, which at the technical level provides a foundational framework for these features; v24.1 further integrates Stellar-Core v24.1.0 to continue this technical roadmap, but activating smart contracts and dApps is an official decision that the Pi core team needs to make separately, and it is independent of the protocol version upgrade. The current upgrade sequence mainly focuses on the stability of the underlying infrastructure and performance optimizations.
If node operators encounter problems during the v23.0 upgrade process, will the migration difficulty for v24.1 be just as high?
According to confirmation from the Pi core team, v24.1 is a standard internal data migration and has fundamental differences from v23.0: v23.0 requires simultaneous operating system upgrade (Ubuntu 20→24), database upgrade (PostgreSQL 12→16), and protocol migration. Because it involves rewriting database files, backup measures must be done in advance as prevention, and the startup time is longer; v24.1 is simply an internal data migration that does not involve rewriting database files, so it does not require special backup steps. In most cases, migration does not exceed 5 minutes, and the restart time is much faster than v23.0. The difficulty of the v23.0 upgrade mainly comes from the complexity of multi-layer synchronized upgrades, while v24.1 does not have the same complexity.
