pktfmt

Generate RFC-style ASCII packet diagrams from field definitions.

A modern, pip-installable alternative to protocol that works on Windows and modern Python.

Installation

pip install pktfmt

Features

• 20+ built-in protocols - TCP, UDP, IP, DNS, and more
• Custom packet definitions - inline format or JSON files
• Unicode box drawing - pretty output for modern terminals
• Variable-length fields - with distinct visual styling
• Cross-platform - works on Windows, macOS, and Linux
• Modern Python - supports Python 3.8+

Quick Start

# Show a built-in protocol
pktfmt tcp

# List all available protocols
pktfmt --list

# Custom inline format
pktfmt "Type:16,Length:16,Payload:*"

# Pretty Unicode output
pktfmt udp --unicode

Usage

Built-in Protocols

$ pktfmt tcp
 0                  1                  2                  3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          Source Port          |        Destination Port       |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                        Sequence Number                        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                     Acknowledgment Number                     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Data Of|Reserve|C|E|U|A|P|R|S|F|             Window            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|            Checksum           |         Urgent Pointer        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
:                            Options                            :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Custom Inline Format

$ pktfmt "Type:16,Length:16,Payload:*"
 0                  1                  2                  3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|              Type             |             Length            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
:                            Payload                            :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

JSON File Format

pktfmt packet.json

{
  "name": "MyPacket",
  "fields": [
    {"name": "Type", "bits": 16},
    {"name": "Length", "bits": 16},
    {"name": "Payload", "bits": "*"}
  ]
}

Unicode Output

$ pktfmt udp --unicode
 0                  1                  2                  3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐
│          Source Port          │        Destination Port       │
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
│             Length            │            Checksum           │
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
┊                              Data                             ┊
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

Options

pktfmt <input> [options]

Options:
  -l, --list              List all built-in protocols
  -b, --bits-per-row N    Bits per row (default: 32)
  -s, --style STYLE       Output style: ascii, unicode
  -u, --unicode           Shortcut for --style unicode
  -o, --output FILE       Write output to FILE instead of stdout
  --no-ruler              Omit the bit number header
  -v, --version           Show version

Pass '-' as the input to read a JSON packet definition from stdin:
  cat packet.json | pktfmt -

Field Syntax

• Name:N - Fixed-width field of N bits
• Name:* - Variable-length field (rendered with : or ┊ borders)

Built-in Protocols

Why pktfmt?

• Actually installs via pip - protocol requires manual setup.py installation
• Works on modern Python - protocol uses deprecated distutils
• Works on Windows - proper UTF-8 handling
• Actively maintained - PRs get merged
• Unicode support - pretty box drawing characters
• More protocols - 20+ built-in, vs ~10 in protocol

License

MIT