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
  • Docker
  • Kubernetes (kind)
• Key Features
• Prerequisites
  • Operating Systems
  • Shell Dependencies
• Getting Started
  • Install From PyPI (Library Only)
  • 1) Clone
  • 2) Install
  • 3) Activate The Virtual Environment
  • 4) Configure System Settings
  • 5) Run The FastAPI Service Launcher
  • 6) (Optional) Serve The Documentation
  • 7) Explore The API
• 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.0.20.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}

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:

• Install kind
• Deploy PyPNM
• kind + FreeLens (VM)

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:

pip install pypnm-docsis

Uninstall and cleanup:

pip uninstall pypnm-docsis
rm -f ~/.ssh/pypnm_secrets.key

For full FastAPI service usage and development, use the repository-based flow below.

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: source ~/.bashrc && config-menu
• System Configuration Reference: field-by-field descriptions and defaults If you installed with --pnm-file-retrieval-setup, it runs automatically and backs up system.json first.

5) Run the FastAPI service launcher

HTTP (default: http://127.0.0.1:8000):

pypnm

Development hot-reload:

pypnm --reload

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

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

• CM-SP-MULPIv3.1
• CM-SP-CM-OSSIv3.1
• CM-SP-MULPIv4.0
• CM-SP-CM-OSSIv4.0
• DOCSIS MIBs

PNM architecture & guidance

• CM-TR-PMA
• CM-GL-PNM-HFC
• CM-GL-PNM-3.1

License

Apache License 2.0 and NOTICE

Next steps

• Review PNM topology options to decide how captures will move through your network.
• Follow the System Configuration guide to tailor system.json for your lab.
• Explore system tools and operational scripts for day-to-day automation.

Maintainer

Maurice Garcia

• Email
• LinkedIn