{"id":29269684,"url":"https://github.com/roxy-wi/pyminiping","last_synced_at":"2026-04-01T19:36:39.503Z","repository":{"id":302399732,"uuid":"1012008635","full_name":"roxy-wi/pyminiping","owner":"roxy-wi","description":"Pure Python ICMP ping with statistics and hop count for Linux","archived":false,"fork":false,"pushed_at":"2026-03-20T07:29:08.000Z","size":41,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-21T00:20:13.683Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roxy-wi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-01T17:02:59.000Z","updated_at":"2026-03-20T07:28:46.000Z","dependencies_parsed_at":"2025-07-02T07:45:29.171Z","dependency_job_id":"13e1293e-4dbd-4a18-aae6-f294e9ef7935","html_url":"https://github.com/roxy-wi/pyminiping","commit_stats":null,"previous_names":["roxy-wi/pyminiping"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/roxy-wi/pyminiping","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roxy-wi%2Fpyminiping","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roxy-wi%2Fpyminiping/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roxy-wi%2Fpyminiping/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roxy-wi%2Fpyminiping/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roxy-wi","download_url":"https://codeload.github.com/roxy-wi/pyminiping/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roxy-wi%2Fpyminiping/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291151,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-04T21:08:10.807Z","updated_at":"2026-04-01T19:36:39.488Z","avatar_url":"https://github.com/roxy-wi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pyminiping\n\nLightweight Python ICMP ping library for monitoring, SRE and networking tools.\n\n![PyPI version](https://img.shields.io/pypi/v/pyminiping)\n![Build status](https://github.com/roxy-wi/pyminiping/actions/workflows/ci.yml/badge.svg)\n![Python versions](https://img.shields.io/pypi/pyversions/pyminiping)\n![License](https://img.shields.io/pypi/l/pyminiping)\n\n`pyminiping` is a pure Python ICMP ping library designed for Linux servers and monitoring tools.\n\nIt sends ICMP echo packets and returns detailed latency statistics such as RTT metrics, packet loss, TTL information, estimated hop count, and p95 latency.\n\nThe library supports **IPv4**, **IPv6**, **DSCP**, **custom TTL**, optional **kernel receive timestamps** via `SO_TIMESTAMPNS`, and includes a **command-line interface**.\n\n⭐ If you find this project useful, please consider starring the repository.\n\n---\n\n# Quick Start\n\nInstall:\n\n```bash\npip install pyminiping\n```\n\nSimple example:\n\n```python\nfrom pyminiping import ping\n\nresult = ping(\"8.8.8.8\")\nprint(result.mean)\n```\n\nExample output:\n\n```text\n0.0042\n```\n\nYou can also export the result as JSON:\n\n```python\nfrom pyminiping import ping\n\nresult = ping(\"8.8.8.8\")\nprint(result.as_json())\nprint(result.as_json(indent=2))\n```\n\nCLI usage:\n\n```bash\nsudo pyminiping 8.8.8.8\n```\n\n---\n\n# Features\n\n- Pure Python ICMP Echo (RAW sockets)\n- IPv4 and IPv6 support\n- Detailed latency statistics\n- Packet loss calculation\n- TTL detection for IPv4\n- Estimated hop count for IPv4\n- OS guess based on IPv4 TTL\n- Customizable parameters:\n  - packet count\n  - timeout\n  - interval\n  - payload size\n  - TTL\n  - DSCP\n- Percentile metrics (p95)\n- Optional kernel receive timestamping with `SO_TIMESTAMPNS`\n- CLI tool included\n- No runtime dependencies\n- Designed for monitoring systems\n\n---\n\n# Installation\n\n## From PyPI\n\n```bash\npip install pyminiping\n```\n\n## From source\n\n```bash\ngit clone https://github.com/roxy-wi/pyminiping.git\ncd pyminiping\npython3 -m pip install .\n```\n\n---\n\n# Example Usage\n\n```python\nfrom pyminiping import ping, DestinationUnreachable\n\ntry:\n    result = ping(\"8.8.8.8\", count=5, timeout=1, interval=0.2)\n    print(result.as_dict())\n\nexcept DestinationUnreachable as e:\n    print(f\"Unreachable: {e.message} (code {e.code})\")\n\nexcept Exception as e:\n    print(f\"Ping failed: {e}\")\n```\n\n---\n\n# Example Output\n\n```python\n{\n    \"sent\": 5,\n    \"received\": 5,\n    \"loss\": 0.0,\n    \"min\": 0.0044,\n    \"max\": 0.0062,\n    \"mean\": 0.0048,\n    \"median\": 0.0045,\n    \"jitter\": 0.0007,\n    \"rtt_list\": [0.0062, 0.0044, 0.0045, 0.0044, 0.0045],\n    \"ttl\": 110,\n    \"hops\": 19,\n    \"os_guess\": \"Windows\",\n    \"p95\": 0.0061\n}\n```\n\n---\n\n# PingResult Object\n\nThe `ping()` function returns a `PingResult` dataclass.\n\n| Field | Description |\n|------|------|\n| sent | Number of packets sent |\n| received | Number of packets received |\n| loss | Packet loss percentage |\n| min | Minimum RTT |\n| max | Maximum RTT |\n| mean | Average RTT |\n| median | Median RTT |\n| jitter | Standard deviation of RTT |\n| p95 | 95th percentile |\n| ttl | TTL from response packet |\n| hops | Estimated hop count |\n| os_guess | OS guess based on IPv4 TTL |\n| rtt_list | List of RTT values |\n\n\nMethods:\n\n| Method | Description |\n|------|------|\n| as_dict() | Return result as a Python dictionary |\n| as_json() | Return result as a JSON string |\n\nProperties:\n\n| Property | Description |\n|------|------|\n| success | `True` if at least one packet was received |\n| packet_loss | Alias for `loss` |\n\nExample:\n\n```python\nfrom pyminiping import ping\n\nresult = ping(\"1.1.1.1\")\n\nprint(result.mean)\nprint(result.packet_loss)\nprint(result.success)\n```\n\n---\n\n# Latency Metrics Explained\n\n`pyminiping` returns several latency metrics commonly used in networking.\n\n| Metric | Description |\n|------|------|\n| min | Fastest response |\n| max | Slowest response |\n| mean | Average latency |\n| median | Middle value |\n| jitter | Standard deviation of latency |\n| p95 | 95th percentile latency |\n| loss | Packet loss percentage |\n\nExample:\n\n```text\nmin=4ms\navg=5ms\nmax=30ms\np95=25ms\n```\n\nMeaning:\n\n- most packets arrive in about 5 ms\n- occasional spikes reach 30 ms\n- 95% of packets arrive under 25 ms\n\n---\n\n# Advanced Usage\n\n## Custom packet size\n\n```python\nping(\"8.8.8.8\", size=128)\n```\n\n## Change interval\n\n```python\nping(\"8.8.8.8\", interval=0.5)\n```\n\n## Set TTL\n\n```python\nping(\"8.8.8.8\", ttl=32)\n```\n\n## Send multiple packets\n\n```python\nping(\"8.8.8.8\", count=10)\n```\n\n## Use DSCP for QoS testing\n\n```python\nping(\"8.8.8.8\", dscp=46)\n```\n\n## Raise exception only when all packets timeout\n\n```python\nping(\"192.0.2.1\", count=3, raise_on_timeout=True)\n```\n\n## Use kernel receive timestamps for more precise RTT\n\n```python\nping(\"8.8.8.8\", use_kernel_timestamp=True)\n```\n\n---\n\n# Command-Line Interface (CLI)\n\nAfter installing `pyminiping`, the CLI tool becomes available.\n\n```bash\npyminiping \u003chost\u003e\n```\n\nExample:\n\n```bash\nsudo pyminiping 8.8.8.8\n```\n\n## CLI Options\n\n| Option | Description | Default |\n|------|-------------|-------|\n| host | Hostname or IP address | required |\n| -c, --count | Number of packets | 4 |\n| -t, --timeout | Timeout per packet (seconds) | 1 |\n| -i, --interval | Interval between packets | 0.1 |\n| -s, --size | Payload size in bytes | 8 |\n| --ttl | Outgoing TTL / hop limit | system default |\n| --dscp | DSCP value (0–63) | not set |\n| --show-rtts | Print per-packet RTT | disabled |\n| -j, --json | Output JSON | disabled |\n| --precise | Use kernel receive timestamps (`SO_TIMESTAMPNS`) | disabled |\n\n## CLI Examples\n\nBasic ping:\n\n```bash\nsudo pyminiping 8.8.8.8\n```\n\nSend multiple packets:\n\n```bash\nsudo pyminiping 8.8.8.8 -c 10\n```\n\nCustom interval:\n\n```bash\nsudo pyminiping 8.8.8.8 -i 0.5\n```\n\nSet TTL:\n\n```bash\nsudo pyminiping 8.8.8.8 --ttl 32\n```\n\nShow packet RTTs:\n\n```bash\nsudo pyminiping 8.8.8.8 --show-rtts\n```\n\nJSON output:\n\n```bash\nsudo pyminiping 8.8.8.8 -j\n```\n\nUse kernel receive timestamps:\n\n```bash\nsudo pyminiping 8.8.8.8 --precise\n```\n\n---\n\n# Precise Timing Mode\n\n`pyminiping` can use Linux kernel receive timestamps via `SO_TIMESTAMPNS` for more accurate packet receive timing.\n\nBenefits:\n\n- more stable RTT measurement under CPU load\n- lower user-space timing jitter\n- useful for latency-sensitive checks\n\nExample:\n\n```python\nresult = ping(\"8.8.8.8\", use_kernel_timestamp=True)\n```\n\nCLI:\n\n```bash\nsudo pyminiping 8.8.8.8 --precise\n```\n\nNotes:\n\n- this mode is Linux-specific\n- support depends on the running Python build and platform socket constants\n- if your environment does not expose `SO_TIMESTAMPNS`, precise mode may be unavailable\n- it improves receive-side timing only\n\n---\n\n# Common DSCP values\n\n| Name | DSCP | Use Case |\n|-----|-----|----------|\n| Default | 0 | Best effort |\n| CS1 | 8 | Background traffic |\n| AF11 | 10 | Low priority |\n| AF21 | 18 | Standard |\n| AF41 | 34 | High priority |\n| EF | 46 | Voice / real-time |\n\n---\n\n# Comparison with system ping\n\n| Feature | system ping | pyminiping |\n|------|------|------|\n| ICMP Echo | ✔ | ✔ |\n| IPv4 | ✔ | ✔ |\n| IPv6 | ✔ | ✔ |\n| RTT statistics | ✔ | ✔ |\n| Jitter calculation | ✖ | ✔ |\n| Percentiles | ✖ | ✔ |\n| Python API | ✖ | ✔ |\n| JSON output | ✖ | ✔ |\n| DSCP support | Limited | ✔ |\n| Custom TTL | ✔ | ✔ |\n| Kernel timestamp mode | Limited | ✔ |\n\n---\n\n# Use Cases\n\nTypical applications:\n\n- monitoring systems\n- SRE tooling\n- network diagnostics\n- infrastructure automation\n\nExample monitoring check:\n\n```python\nresult = ping(\"1.1.1.1\", count=3)\n\nif not result.success:\n    alert(\"Connectivity issue\")\n```\n\n---\n\n# Performance Notes\n\n`pyminiping` is designed to be lightweight:\n\n- minimal memory usage\n- no subprocess calls\n- no external dependencies\n- suitable for monitoring agents\n\nFor most checks, normal timing is enough. Use `use_kernel_timestamp=True` or `--precise` only when you need more stable receive-side timing.\n\n---\n\n# Security\n\n`pyminiping` uses RAW sockets and requires elevated privileges.\n\nRun with sudo:\n\n```bash\nsudo pyminiping 8.8.8.8\n```\n\nAllow Python RAW sockets:\n\n```bash\nsudo setcap cap_net_raw+ep $(readlink -f $(which python3))\n```\n\n---\n\n# Troubleshooting\n\n## Error: Root privileges or CAP_NET_RAW are required to create RAW socket\n\nRun the script with root privileges or allow RAW socket capability.\n\n## Error: Cannot resolve host\n\nCheck DNS resolution or use an IP address instead of a hostname.\n\n## Error: SO_TIMESTAMPNS is not available on this platform\n\nPrecise mode depends on Linux platform support and the Python socket build.\n\nYou can:\n\n- run without `use_kernel_timestamp=True`\n- avoid `--precise`\n- use a Python build that exposes the `SO_TIMESTAMPNS` socket option\n\n---\n\n# License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froxy-wi%2Fpyminiping","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froxy-wi%2Fpyminiping","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froxy-wi%2Fpyminiping/lists"}