Install a Pi Node on Linux From Scratch — Synced Before the Sept 15 Deadline

The Deadline Is Real: v27.1 by September 15

Pi Network's protocol upgrade document states it plainly: "All nodes are required to be on version 27.1 by 09/15/2026." The upgrade chain shows 19.1 through 26.1 already completed, 27.1 as the active target, and 28.0 explicitly marked "DO NOT start upgrading." Miss the window and Pi's own documentation warns that missed steps "may be necessary to resynchronize the node from scratch" — days of waiting while your ledger catches up.

The upgrade chain, straight from the doc: 19.1 → 19.6 → 19.9 → 20.2 → 21.2 → 22.1 → 23.0 → 24.1 → 25.2 → 26.1 → ➡️ 27.1 → 28.0. Three rules keep you safe at every step: never skip a version (each release upgrades from the one before it — a skipped step can force that full resync), don't upgrade all your nodes at once (stagger them so one bad move doesn't take the whole fleet down), and trust only official channels — the Pi Node app, minepi.com, or the official Pi Core Team docs. Never a random repo or a "pi-node-official" clone.

The good news: installing a Pi node on Linux is no longer a Docker-compose puzzle. Pi ships an official APT repository at apt.minepi.com and a pi-node CLI that manages Docker for you. A fresh install takes minutes, and an existing node upgrades with one command. The planned downtime is under five minutes.

This guide walks the full path — fresh install, upgrade, legacy Docker migration, and the day-2 stuff most tutorials skip: ports, logs, and keeping your NODE_SEED private. The video above shows every step on screen.

Why Run a Pi Node At All?

Pi launched in March 2019, moved to Testnet in 2020, Enclosed Mainnet in December 2021, and opened its network on February 20, 2025. As of Pi's own published recaps, the network counts over 60 million engaged Pioneers, more than 17.5 million KYC-verified accounts, and over 350,000 Testnet nodes. The stated mission: "Build a cryptocurrency and smart contracts platform secured and operated by everyday people."

Now the honest part, because most Pi content skips it. The whitepaper's node bonus is a mining-rate multiplier, described as N(I) = node_factor × tuning_factor × I, where the tuning factor normalizes your node contribution to up to 10 times the base mining rate. That bonus comes from the 65-billion-coin mining pool (of a 100 billion max supply). Testnet nodes earn no mining rewards — that's Pi's own wording.

There is no official per-node payout amount or date published anywhere. Anyone quoting you a specific Pi-per-day figure for running a node is guessing. You run a node to secure the network and hold your place in it — the whitepaper is the only source that matters for the reward mechanics, and it lives at minepi.com/white-paper.

What Hardware You Need

Pi's Linux page lists the requirements as text (not just images):

Disk: 150GB to start, ideally 300GB — the blockchain ledger keeps growing
CPU: 4 vCPUs
RAM: 4GB minimum
OS: Debian-based Linux; Ubuntu 24.04 LTS x64 is the suggested pick

That's more than a $5 entry-tier VPS, but a properly specced VPS still beats leaving your home machine on 24/7 — no electricity cost anxiety, no ISP port headaches, and the node survives reboots you don't have to babysit. My cheapest VPS guide compares current plans against exactly these node specs.

Step 1 — Add Pi's Official APT Repository

These commands come straight from Pi's official Linux install page (minepi.com/pi-blockchain/pi-node/linux/):

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

Add the signing key and repository:

curl -fsSL https://apt.minepi.com/repository.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/pinetwork-archive-keyring.gpg
sudo chmod a+r /etc/apt/keyrings/pinetwork-archive-keyring.gpg
echo 'deb [arch=amd64 signed-by=/etc/apt/keyrings/pinetwork-archive-keyring.gpg] https://apt.minepi.com stable main' | sudo tee /etc/apt/sources.list.d/pinetwork.list > /dev/null

Step 2 — Install and Initialize the Node

sudo apt-get update
sudo apt-get install pi-node
pi-node --version
pi-node initialize

pi-node initialize walks you through linking your Pi account, setting the Pi folder, and generating your node key. For scripted setups, non-interactive flags exist: --pi-folder, --docker-volumes, --node-private-key, --postgres-password, and --start-node. The CLI pulls the official Docker images and manages the containers itself — no systemd units to write.

Watch it come up:

pi-node status
pi-node logs -f
pi-node start     # stop / restart also available

Not on Linux? The Other Install Methods

Windows and Mac users install the Pi Node desktop app from minepi.com/pi-node and put Docker Desktop alongside it — the app walks you through pairing with your Pi account and applies protocol updates itself. And if you'd rather run a low-power box, any x64 machine works: a Raspberry Pi on a 64-bit OS counts, older 32-bit Pis don't. Install Docker first, then pick up at Step 1 above:

curl -fsSL https://get.docker.com | sh

That's Docker's official install script — verify it at docs.docker.com before running it anywhere.

Step 3 — Upgrade a Running Node to v27.1

Two official paths, depending on how your node is managed.

If your node runs on a manual docker-compose setup — the path shown in the video — edit docker-compose.yml and point the image line at the official v27.1 tag:

image: pinetwork/pi-node-docker:organization-mainnet-v1.0-p27.1.0

Then bring the stack back up and watch it upgrade and resync:

docker compose up -d

If your node is on the CLI setup, the upgrade is a single line:

pi-node update-protocol

Then monitor until the state reads "Synced" — not "Syncing":

watch pi-node status

Also grab the newest CLI itself, so your package matches the protocol:

sudo apt-get update
sudo apt-get install --only-upgrade pi-node

Three sanity checks before you call it done: the status page reads "Synced" (not just "running"), the ingest_latest_ledger value from curl http://localhost:31401 matches api.mainnet.minepi.com, and the version reads 27.1. Then stop — don't jump ahead to 28.0 until Pi's official channels say it's your turn.

Step 4 — Migrating Off Legacy Docker

Nodes installed the old way (manual docker-compose) can move to the CLI. From Pi's official migration instructions:

docker compose down

Back up your volumes, then pull your secrets from mainnet.env:

grep -E 'NODE_SEED|NODE_PRIVATE_KEY' mainnet.env
grep 'POSTGRES_PASSWORD' mainnet.env

Re-initialize with those values using pi-node initialize and its flags (--node-private-key, --postgres-password). Your node keeps its identity — you're changing the manager, not the node.

To confirm the migration finished, compare the ledger: curl http://localhost:31401 returns a JSON blob with ingest_latest_ledger. Match it against api.mainnet.minepi.com — when the numbers match, you're fully caught up. The local number only updates at the end, so don't panic mid-sync.

Step 5 — Ports, Logs, and the One Rule

The official compose mapping exposes three ports — 31401:8000, 31402:31402, 31403:1570. Ignore older tutorials that quote a 31400-31409 range; open exactly these on your firewall so your node can peer:

sudo ufw allow 31401/tcp
sudo ufw allow 31402/tcp
sudo ufw allow 31403/tcp

Daily-driver commands: pi-node status, pi-node logs -f, pi-node start/stop/restart.

And Pi's own words, worth framing: "Always keep your NODE_SEED secret. Do not share it." Your seed is your node's identity. Any tutorial, DM, or "support agent" asking for it is trying to take your node — and possibly your account.

If You Miss September 15

The consequence isn't necessarily a dead node — it's a resync. Depending on when you catch up, that means days of your node downloading and validating the ledger from zero while the network moves on. The fix is boring and cheap: run the upgrade this week (Step 3), watch the status flip to Synced, done.

Frequently Asked Questions

Can I run a Pi node on a VPS?

Yes. Pi's requirements are hardware specs, not location rules — 150GB+ disk, 4 vCPUs, 4GB RAM, and a Debian-based OS are all standard VPS line items. A VPS also sidesteps the two biggest home-node complaints: residential internet's port restrictions and a machine that has to stay on around the clock.

How long does the v27.1 upgrade take?

Pi's documentation puts planned downtime at under five minutes. The full sync to "Synced" status takes longer on first install — the node validates the whole ledger — but an in-place protocol upgrade on an already-synced node is quick. Back up your volumes first, and don't run pi-node update-protocol on several nodes at the same moment.

Do Pi nodes earn rewards?

The whitepaper's node bonus is a mining-rate multiplier — up to 10 times the base rate, funded from the 65-billion mining pool. Testnet nodes earn nothing. No official Mainnet per-node payout amount or date has been published, so treat any specific number you see elsewhere as speculation.

What's the difference between protocol v27.1 and node software 0.6.3?

Two different version numbers for two different things. Protocol v27.1 is the blockchain protocol version your node must run by September 15 — that's what pi-node update-protocol moves. Node software 0.6.3 is the current release of the desktop/CLI application itself, distributed through Pi's GitHub releases and the apt repository. You may see both in pi-node status; the deadline applies to the protocol version.

Cost Summary

Component	Cost
Pi Node software	Free (open source)
VPS (150GB+ disk, 4 vCPU, 4GB RAM)	Varies by provider — see comparison
Electricity	$0 (it runs on the VPS, not your desk)

For current plan prices matched against these node specs, check the cheapest VPS comparison — it's updated whenever providers change pricing.

What's Next

After the deadline, the interesting question is what Pi does next — 28.0 is already on the upgrade doc as a name only. If your node is now Synced, drop a comment with your sync time; it helps others calibrate expectations. And if you're building out a node rack, the crypto node operations guide covers the evaluation framework I use before committing hardware to any network.

Disclaimer: Some links are affiliate links. If you use them, I may earn a small commission at no extra cost to you. My content is educational and not financial advice.