FAQ & Troubleshooting¶

General¶

What is Open-IPv8-Lab?¶

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.

Does IPv8 replace IPv6?¶

No. IPv8 is an independent experimental protocol for research and education. IPv6 remains the IETF production standard for next-generation Internet addressing.

Does this require root / raw sockets?¶

No. Everything runs in userspace as a normal user process. No kernel modules, no raw sockets, no privilege escalation.

What operating systems are supported?¶

Linux, macOS, and Windows (including WSL2). Any platform with Python 3.11+ should work.

Where is the spec?¶

draft-thain-ipv8-02 — the full IETF Internet-Draft. The Spec Coverage doc maps every section to source code.

Installation¶

`pip install` fails with "requires Python >= 3.11"¶

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]"

`ipv8lab: command not found` after install¶

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/ipv8lab

If you installed without -e, reinstall in editable mode:

pip install -e ".[dev]"

`ModuleNotFoundError: No module named 'ipv8lab'`¶

You're running Python outside the venv. Activate it first:

source .venv/bin/activate

Dependency conflict with `typer` / `rich` / `textual`¶

Minimum 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 pyyaml

CLI Usage¶

How do I see all available commands?¶

ipv8lab --help

This lists all 35 sub-commands. For a specific command:

ipv8lab addr --help
ipv8lab zone --help

Commands fail with `Error: Missing argument`¶

Most 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.1

How do I get JSON output?¶

Add --json to any command:

ipv8lab addr parse 64496.192.0.2.1 --json
ipv8lab zone status --json
ipv8lab bench run --json

`zone oauth-issue` / `zone dhcp8-lease` fails¶

Zone 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 --json

For the full lifecycle, see Examples — Zone Server workflow.

`route simulate` says "config file not found"¶

The config must be a .yaml file. Check it exists:

ipv8lab route simulate --config examples/two_asn_demo.yaml

TUI dashboard doesn't render properly¶

Ensure your terminal supports 256 colors and Unicode. Try:

export TERM=xterm-256color
ipv8lab tui run

On Windows, use Windows Terminal (not cmd.exe).

Testing¶

How do I run all tests?¶

pytest -v

All 1827 tests should pass. To run tests for a specific module:

pytest tests/test_address.py -v
pytest tests/test_route.py -v

Tests pass locally but fail in CI¶

Check Python version — CI uses 3.11+. Also ensure all dev dependencies are installed:

pip install -e ".[dev]"

How do I run linting and type checks?¶

ruff check src/ tests/
mypy src/

Common Errors¶

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]"`

Still stuck?¶

Check CLI Reference for exact command syntax
Check Examples for step-by-step walkthroughs
Check Glossary for unfamiliar terms
Open an issue on GitHub