PyPNM - Proactive Network Maintenance Toolkit
PyPNM is a DOCSIS 3.x/4.0 Proactive Network Maintenance toolkit for engineers who want repeatable, scriptable visibility into modem health. It can run purely as a Python library or as a FastAPI web service for real-time dashboards and offline analysis workflows.
Table of contents
- Choose your path
- Kubernetes | Docker
- Key Features
- Prerequisites
- Getting Started
- Documentation
- Gallery
- SNMP Notes
- CableLabs Specifications & MIBs
- PNM Architecture & Guidance
- License
- Maintainer
Choose your path
| Path | Description |
|---|---|
| Kubernetes deploy (kind) | Run PyPNM in a local kind cluster (GHCR image). |
| Docker deploy | Install and run the containerized PyPNM service. |
| Use PyPNM as a library | Install pypnm-docsis into an existing Python environment. |
| Run the full platform | Clone the repo and use the full FastAPI + tooling stack. |
Kubernetes | Docker
Docker (Recommended) - Install Docker | Install PyPNM Container | Commands
Fast install (helper script; latest release auto-detected):
TAG="v1.6.4.0"
PORT=8080
curl -fsSLo install-pypnm-docker-container.sh \
https://raw.githubusercontent.com/PyPNMApps/PyPNM/main/scripts/install-pypnm-docker-container.sh
chmod +x install-pypnm-docker-container.sh
sudo ./install-pypnm-docker-container.sh --tag ${TAG} --port ${PORT}
Update an existing Docker deployment in place:
sudo ./install.sh --update
sudo ./install.sh --update v1.5.3.0
--update stops the existing PyPNM compose stack, removes old PyPNM
containers/images, then reinstalls using the requested tag or the latest
release when no tag is provided. Internally, install.sh delegates to the
Docker update helper under scripts/.
If Docker isn’t on your host yet, follow the Install Docker prerequisites guide first.
More Docker options and compose workflows: PyPNM Docker Installation and Developer Workflow.
Kubernetes (kind) dev clusters
Kubernetes quick links:
We continuously test the manifests with a kind-based CI smoke test (Kubernetes (kind) badge above). Follow the kind quickstart or the detailed deployment guide to run PyPNM inside a local single-node cluster; multi-node scenarios are not covered yet (see pros/cons).
Script-only deployment (no repo clone) is documented in PyPNM deploy.
Prerequisites
Operating systems
Linux, validated on:
- Ubuntu 22.04 LTS
- Ubuntu 24.04 LTS
Other modern Linux distributions may work but are not yet part of the test matrix.
Shell dependencies
From a fresh system, install Git:
sudo apt update
sudo apt install -y git
Python and remaining dependencies are handled by the installer.
Getting started
Install from PyPI (library only)
If you only need the library, install from PyPI:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install pypnm-docsis
Uninstall and cleanup:
pip uninstall pypnm-docsis
rm -f ~/.ssh/pypnm_secrets.key
FastAPI Service and Development
1) Clone
git clone https://github.com/PyPNMApps/PyPNM.git
cd PyPNM
2) Install
Run the installer:
./install.sh
Common flags (use as needed):
| Flag | Purpose |
|---|---|
--development |
Installs Docker Engine + kind/kubectl. See Development Install. |
--clean |
Removes prior install artifacts (venv/build/dist/cache) before installing. Preserves data and system configuration. |
--purge-cache |
Clears pip cache after activating the venv (use with --clean when troubleshooting stale installs). |
--pnm-file-retrieval-setup |
Launches tools/pnm/pnm_file_retrieval_setup.py after install. See the PNM File Retrieval Overview. |
--demo-mode |
Seeds demo data/paths for offline exploration. See the demo mode guide. |
--production |
Reverts demo-mode changes and restores your previous system.json backup. |
Installer extras: adds shell aliases when available; source your rc file once to pick them up.
3) Activate the virtual environment
If you used the installer defaults, activate the .env environment:
source .env/bin/activate
4) Configure system settings
System configuration lives in deploy/docker/config/system.json.
- Config menu:
pypnm config-menu - System Configuration Reference: field-by-field descriptions and defaults
5) Run the FastAPI service launcher
HTTP (default: http://127.0.0.1:8000):
pypnm serve
Expose PyPNM on all IPv4 interfaces assigned to the host:
pypnm serve --host-all
Bind to one specific interface or address:
pypnm serve --host 192.168.1.20
Development hot-reload:
pypnm serve --reload
Optional route policy controls:
pypnm serve --mute-tags "PNM Operations - Multi-Downstream OFDM RxMER"
pypnm serve --mute-tags "Orchestrator,Operational" --mute-tags-hard
6) (Optional) Serve the documentation
HTTP (default: http://127.0.0.1:8001):
mkdocs serve
7) Explore the API
Installed services and docs are available at the following URLs:
| Git Clone | Docker |
|---|---|
| FastAPI Swagger UI | FastAPI Swagger UI |
| FastAPI ReDoc | FastAPI ReDoc |
| MkDocs docs | MkDocs docs |
Recommendations - Postman-PyPNMApps-API
The companion Postman-PyPNMApps-API repo provides a maintained Postman collection, environments, and Postman visualizers for PyPNM FastAPI endpoints. It is intended for quick endpoint testing, capture/analysis workflow validation, and operator-friendly response visualization (tables/graphs) without writing custom client code.
Documentation
- Docs hub - task-based entry point (install, configure, operate, contribute).
- FastAPI reference - Endpoint details and request/response schemas.
- Python API reference - Importable helpers and data models.
SNMP notes
- SNMPv2c is supported
- SNMPv3 is currently stubbed and not yet supported
CableLabs specifications & MIBs
PNM architecture & guidance
License
Next steps
- Review PNM topology options to decide how captures will move through your network.
- Follow the System Configuration guide to tailor
system.jsonfor your lab. - Explore system tools and operational scripts for day-to-day automation.
Maintainer
Maurice Garcia
1 maintainer
Release files for pypnm-docsis 1.6.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pypnm_docsis-1.6.4.0.tar.gz | 1.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pypnm_docsis-1.6.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.8 MB
Release files / pypnm_docsis-1.6.4.0.tar.gz
| Download URL | pypnm_docsis-1.6.4.0.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
663462e48da55f046e602e7d20d3da119080b2f98d5e2a72a5cf16d2f8a964b2
|
|
BLAKE2b-256 checksum How to use checksums |
743443b2497d36b2deaa0182a3c26d65adedb308e3ddf22d339db2ef82304d39
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / pypnm_docsis-1.6.4.0-py3-none-any.whl
| Download URL | pypnm_docsis-1.6.4.0-py3-none-any.whl |
|---|---|
| Size | 1.4 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cd83fd3fcd68832aa44f7520673b9e5363dd7300204c75c60d03662cecb44b1c
|
|
BLAKE2b-256 checksum How to use checksums |
963fd9347484317128cb2327d4ec6eb50f8105ba80eff18f92aa7f0abbe84477
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
