Skip to main content

ifpretty

Prettify and enrich ifconfig output. A terminal tool that turns the raw, cryptic ifconfig dump into an aligned, colorized, annotated view — and, on demand, layers on live system data, a 1‑hour bandwidth graph, run‑to‑run diffing, and an interactive browser map of your whole network. Built on rich.

ifpretty

Install

pip install ifpretty

Requires Python ≥ 3.9. The only runtime dependency is rich.

Quick start

  • ifpretty — run it bare; it runs ifconfig for you and prints the essentials view.
  • ifpretty -v — the full, verbose view (every field).
  • ifconfig | ifpretty — or pipe ifconfig in yourself.
  • ifpretty en0 en6 — limit to specific interfaces.

Flags compose, e.g. ifpretty -l -d (live data + diff), ifpretty -t -v (full table).


Output views

The default reads ifconfig from stdin if piped, otherwise runs ifconfig itself (optionally limited to the interface names you pass).

View Flag Best for
Essentials (boxed) (default) day‑to‑day: identity, routable IPs, gateway, throughput
Verbose -v / --verbose everything: flags, options, nd6, media, link‑local, bridge config
Records -r / --records a compact, low‑chrome label/value list
Table -t / --table one wide table (≤ 240 cols) to scan many interfaces at once

The essentials view shows each interface's identity, routable addresses (with scope), gateway and throughput, and collapses down / address‑less interfaces to a single dim line to cut noise. -v expands them and shows every field.


Always‑on enrichment (offline, no network)

Every view annotates what ifconfig leaves cryptic — all derived locally, no network calls:

  • Interface role — loopback / Ethernet·Wi‑Fi / VPN·tunnel / bridge / AWDL / …
  • IP scope for each address — loopback / link-local / ULA / private / global; IPv4 also shows the network + usable‑host count.
  • MAC kind (universal vs locally‑administered/random), OUI vendor (from a bundled IEEE registry — no network), shared‑MAC notes (e.g. bridge members sharing an address), and EUI‑64 detection.
  • Media speed/duplex, with a ⚠ warning on half‑duplex; jumbo / sub‑1280 MTU notes.
  • Decoded flag / option / nd6 bitfields; IPv6 attributes aligned into columns.
  • A one‑line overview (interface count, default route, traffic totals).
en0  ● active  ·  Ethernet/Wi-Fi
  ether  14:7d:da:00:00:01   (universal · Apple, Inc.)
  inet   192.168.1.201/24  · private
  inet6  2001:…:60a6/64     · global

Live system data — -l / --live (macOS)

Cross‑references the running system and adds, per interface:

  • default route + gateway, friendly hardware‑port names (e.g. "Wi‑Fi"),
  • DNS servers + search domains, DHCP server + lease,
  • traffic counters (bytes and packets) and error / collision counts.
ifpretty -l

Gateway health — -c / --check (macOS)

Pings the default gateway and reports latency (or unreachable).

ifpretty -c

Public IP — -w / --wan (opt‑in, external)

Looks up your public IP + ASN / ISP / geo via ipapi.co and adds it to the overview line. Strictly opt‑in (it sends your public IP to a third party); the result is cached ~1 h, times out fast, and degrades silently offline.

ifpretty -w

What changed — -d / --diff

Every run records a snapshot of the stable interface state (up/down, addresses, MAC, mtu, media, gateway — deliberately not volatile counters). --diff prints what changed since the previous run before the normal view:

ifpretty -d
Changes since last run (3m ago):
  + en7 appeared
  - en1 removed
  ~ en0
      inet: +192.168.1.50/24  -192.168.1.201/24

1‑hour bandwidth graph — --record

ifconfig only has cumulative counters, so to graph bandwidth you schedule a tiny recorder; the per‑interface sparkline + link‑utilization gauge then appear automatically:

# once, e.g. in `crontab -e` — use the absolute path:
* * * * * $(command -v ifpretty) --record
1h in    ▁▁▁▂▄█▅▂▁▁▁▁   peak 10.0 Mbps
1h out   ▁▂▂▄▆█▄▂▂▁▁▁   peak 533.3 Kbps
link use ████░░░░░░     40% of 1000 Mbps

Network map — --map

Opens an interactive browser graph of your whole network in three zones:

💻 Your computer (interfaces) · 🏠 Local network (gateway + LAN devices/peripherals from the ARP table) · 🌐 Internet (the traceroute path out to the target).

ifpretty --map            # default target 1.1.1.1
ifpretty --map 8.8.8.8    # trace to a specific target

Every IP is enriched with everything useful:

  • host — reverse‑DNS name (e.g. a hop's core.isp.net, a printer's hp.local)
  • company / org, ISP, ASN (e.g. AS13335 Cloudflare), country / city
  • LAN devices also show their OUI vendor (maker) and MAC.

Public IPs (hops + target) are resolved in a single batched whois/geo lookup; LAN IPs get local reverse‑DNS. Hover any node for the full detail; node labels show the company + country inline. Rendered with vis-network (loaded from a CDN) into a self‑contained HTML file that opens automatically.

Legend — -x / --explain

Appends a legend explaining every flag / option / nd6 bit seen in the output.

Refresh vendor DB — --update-oui

Downloads the latest IEEE OUI registry into the cache (overrides the bundled copy used for MAC → vendor lookups).


All flags

Flag Does
(none) essentials view; runs ifconfig if nothing is piped
-v, --verbose show every field; expand collapsed interfaces
-r, --records compact label/value layout
-t, --table single wide table (≤ 240 cols)
-l, --live route, traffic, names, DNS, DHCP (macOS)
-c, --check ping the default gateway (macOS)
-w, --wan public IP / ASN / geo (opt‑in, external)
-d, --diff show changes since the previous run
-x, --explain append a flag/option legend
--map [TARGET] interactive browser network map (default target 1.1.1.1)
--record sample byte counters and exit (for the 1h graph)
--update-oui refresh the IEEE vendor database and exit
interfaces… limit to these interface names

Environment

  • NO_COLOR=1 disables color; CLICOLOR_FORCE=1 forces it when piped.
  • IFPRETTY_HISTORY — bandwidth‑samples file (default ~/.cache/ifpretty/samples.csv).
  • IFPRETTY_CACHE — cache dir for the WAN lookup, refreshed OUI DB, and the diff snapshot (default ~/.cache/ifpretty/).

The parsing, formatting and offline enrichment work anywhere you can pipe ifconfig output in. --live / --check / --record rely on macOS tools (route, netstat, networksetup, scutil, ipconfig, ping) and no‑op (or degrade) elsewhere. --wan and --map's IP lookup need internet and fail gracefully without it.

Architecture

One responsibility per module:

Module Responsibility
model dataclasses Inet / Inet6 / Interface
parse raw ifconfig text → interface model
enrich derivations, OUI, system (--live/--check), history, --wan, snapshot/diff
formatting model values → styled (rich‑markup) strings; layout field rows
render render strategies (boxed / records / table) + overview / legend / diff
topology --map: traceroute + ARP + per‑IP whois/rDNS → vis‑network graph
cli acquire input → parse → enrich → render

Dependency direction: model ← parse, enrich ← formatting ← render ← cli (no cycles).

Development

python3 -m unittest discover -s tests   # 70 tests (snapshot + unit)
ruff check src tests && mypy src

Layout snapshots are pinned to golden files; regenerate intentionally with REGEN=1 python3 tests/test_ifpretty.py.

License

MIT

Metadata

Release files for ifpretty 0.13.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ifpretty 0.13.1
File Size Uploaded Provenance Actions
ifpretty-0.13.1.tar.gz 428.3 kB Without provenance Details for ifpretty-0.13.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ifpretty 0.13.1
File Interpreter ABI Platform Actions
ifpretty-0.13.1-py3-none-any.whl Python 3 none any Details for ifpretty-0.13.1-py3-none-any.whl

Total release size: 843.5 kB

Release files / ifpretty-0.13.1.tar.gz

Download URL ifpretty-0.13.1.tar.gz
Size 428.3 kB
Tags Source
SHA-256 checksum
How to use checksums
a62f71ec08780324601f42bc006e2fe79a8ef50744bc5ecc8298531f627461c7
BLAKE2b-256 checksum
How to use checksums
3c0a31ac9ea31e580fa62ab992e65939b5c351c3ed23a1c4d7ac4e0f6b453e6b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.11 {"installer":{"name":"uv","version":"0.9.11"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / ifpretty-0.13.1-py3-none-any.whl

Download URL ifpretty-0.13.1-py3-none-any.whl
Size 415.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e85cbc421f57c8271bc28d87d731445033d3583b26bf24ea6e8cd24d080ea4d5
BLAKE2b-256 checksum
How to use checksums
ca43b800f404ac82f6d71988d8af52b2216a0bc664272abf1dcfe68caba29f92
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.11 {"installer":{"name":"uv","version":"0.9.11"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for ifpretty 0.13.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page