An experimental userspace toolkit implementing draft-thain-ipv8-02 — the Internet Protocol Version 8 specification. It is not production networking software and does not modify your system's network stack. See Overview for a full description and IPv8 vs IPv4/IPv6 comparison.
No. IPv8 is an independent experimental protocol for research and education. IPv6 remains the IETF production standard for next-generation Internet addressing.
No. Everything runs in userspace as a normal user process. No kernel modules, no raw sockets, no privilege escalation.
Linux, macOS, and Windows (including WSL2). Any platform with Python 3.11+ should work.
draft-thain-ipv8-02 — the full IETF Internet-Draft. The Spec Coverage doc maps every section to source code.
Upgrade Python. On macOS: brew install python@3.13. On Ubuntu: sudo apt install python3.13. Then recreate the venv:
python3.13 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"The entry point is installed into the venv's bin/. Make sure the venv is activated:
source .venv/bin/activate
which ipv8lab # should print .venv/bin/ipv8labIf you installed without -e, reinstall in editable mode:
pip install -e ".[dev]"You're running Python outside the venv. Activate it first:
source .venv/bin/activateMinimum versions: typer>=0.12.0, rich>=13.0.0, textual>=0.60.0, pyyaml>=6.0.0. If you have older versions:
pip install --upgrade typer rich textual pyyamlipv8lab --helpThis lists all 35 sub-commands. For a specific command:
ipv8lab addr --help
ipv8lab zone --helpMost commands use positional arguments, not --option flags. Check --help for the correct syntax:
# Wrong:
ipv8lab addr parse --address 64496.192.0.2.1
# Right:
ipv8lab addr parse 64496.192.0.2.1Add --json to any command:
ipv8lab addr parse 64496.192.0.2.1 --json
ipv8lab zone status --json
ipv8lab bench run --jsonZone Server commands are stateful — they require zone init first. However, module-level state is lost between separate CLI process invocations. For quick demos, use:
ipv8lab zone status --jsonFor the full lifecycle, see Examples — Zone Server workflow.
The config must be a .yaml file. Check it exists:
ipv8lab route simulate --config examples/two_asn_demo.yamlEnsure your terminal supports 256 colors and Unicode. Try:
export TERM=xterm-256color
ipv8lab tui runOn Windows, use Windows Terminal (not cmd.exe).
pytest -vAll 1827 tests should pass. To run tests for a specific module:
pytest tests/test_address.py -v
pytest tests/test_route.py -vCheck Python version — CI uses 3.11+. Also ensure all dev dependencies are installed:
pip install -e ".[dev]"ruff check src/ tests/
mypy src/| Error | Cause | Fix |
|---|---|---|
command not found: ipv8lab |
venv not activated | source .venv/bin/activate |
Missing argument 'ADDRESS' |
Using --option instead of positional arg |
Check --help, use positional args |
No such file or directory: '*.yaml' |
Wrong config path | Use examples/two_asn_demo.yaml |
ModuleNotFoundError |
Wrong Python / no venv | Activate venv or reinstall |
TypeError: randbelow() |
Python < 3.11 | Upgrade to Python 3.11+ |
ImportError: typer |
Missing dependency | pip install -e ".[dev]" |
- Check CLI Reference for exact command syntax
- Check Examples for step-by-step walkthroughs
- Check Glossary for unfamiliar terms
- Open an issue on GitHub