PySubnet is a beginner-friendly tool that automates the complex process of setting up multi-node Substrate blockchain networks. Whether you're a blockchain developer learning Substrate or deploying production networks, PySubnet handles all the tedious setup work for you.
- 🔑 Generates all cryptographic keys for your validator authorities (AURA, BABE, GRANDPA)
- 📁 Creates proper directory structure for your network nodes
- ⚙️ Prepares a chainspec with bootnodes and validator keys
- 🔗 Sets up p2p keys (libp2p keys for bootnodes list)
- 💸 Funds starting balances for any number of accounts for you without having to manually edit chainspec files. (See example in nodes.toml)
- 🏃♂️ Launches your network with a single command (
-r) - 🎨 Interactive CLI with beautiful, colorful output (
-i)
- Blockchain Developers learning the Substrate framework with multi-node setups
- DevOps Teams for managing multiple sets of keys for separate nodes
- Rapid Prototyping of blockchain applications
uv pip install pysubnet
# or install it as a tool
uv tool install pysubnetpip install git+https://github.com/weezy20/pysubnet.gituvx git+https://github.com/weezy20/pysubnet.git💡 Tip: If you get Python header errors during installation:
- Ubuntu/Debian:
sudo apt install python3-dev- RHEL/Fedora:
sudo dnf install python3-devel- macOS:
xcode-select --install
pysubnetThat's it! PySubnet will automatically start in interactive mode and guide you through the setup.
PySubnet will present you with 5 commonly used consensus options:
- 🟢 PoA (Proof-of-Authority) - Perfect for learning and simple development
- 🟡 PoA + ValidatorSet - PoA with sessions pallet and substrate-validator-pallet for dynamic authority management
Note: To use this pallet (substrate-validator-set) it's recommended to clone it locally and add it to your runtime because as of this writing, it's dependecies seem outdated, but its functionality is unaffected - 🔵 BABE + GRANDPA - Production-ready consensus (like Polkadot)
- 🟣 BABE + GRANDPA + Staking - Full production setup with economic security
- 🔴 Development Mode - Single node for rapid development
When you run pysubnet, it automatically detects if you have a substrate binary and provides:
- 🎨 Beautiful CLI interface with colors and progress bars
- 🤖 Smart substrate detection - automatically switches to interactive mode if no binary found
- ❓ Helpful prompts - clear explanations for each option
- 🔧 Flexible configuration - choose exactly what you need
- 📊 Real-time feedback - see your network being built step by step
# Quick setup with defaults
pysubnet --clean --run
# Or a shorter version
pysubnet -cr
# Custom binary location
pysubnet --bin ./target/release/my-node --run
# Using Docker
pysubnet --docker substrate:latest --run
# Custom chainspec
pysubnet --chainspec ./my-chainspec.json --runCreate advanced network configurations:
pysubnet --config ./network-config.toml --runSee docs/config.md for configuration examples.
PySubnet creates organized directories:
./network/ # Default root directory
├── pysubnet.json # Network configuration & keys
├── chainspec.json # Generated chainspec
├── raw_chainspec.json # Raw chainspec for nodes
├── alice/ # Node directories
│ ├── alice-node-private-key
│ └── chains/<chain folder based on running chainspec>/keystore/
├── bob/
└── charlie/
| Flag | Description | Example |
|---|---|---|
-i, --interactive |
Force interactive mode (default when no substrate binary) | pysubnet -i |
-r, --run |
Launch network after setup | pysubnet -r |
-c, --clean |
Clean existing network directory | pysubnet -c |
--root |
Custom network directory | --root ./my-network |
--bin |
Path to substrate binary | --bin ./substrate |
--docker |
Use Docker image | --docker substrate:latest |
--chainspec |
Base chainspec (dev, local, or file path) |
--chainspec dev |
--config |
Network configuration file | --config ./config.toml |
--account |
Account type (ecdsa or sr25519) |
--account ecdsa |
--poa |
Force basic PoA mode (bypass interactive selection) | --poa |
The first tutorial on substrate is about running a PoA node with 2 or 3 nodes. You can replicate that entire tutorial with pysubnet by running pysubnet -icr --poa --bin <your poa enabled node>.
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- All node data (crypto keys, Account keys, libp2p keys, node IDs) is stored in
pysubnet.json. - The script auto-generates keystores compatible with Substrate’s expected format.
- 🧹 Always use
--clean/-cwhen restarting development to avoid issues. - 📝 Save your pysubnet.json - After having a proper setup, save this file for your future reference, it contains all your network keys and configuration
- 🎯 5 Consensus Options (upgraded from 2)
- 🎨 Enhanced Interactive Mode with beautiful CLI
- 🤖 Smart Binary Detection with automatic fallback
- 📦 Modular Architecture for easier customization
Made with ❤️ for the Substrate community