homenet

A friendly home network troubleshooter that diagnoses common problems and explains them in plain English.

homenet checks your router, DNS, double NAT, UPnP, internet speed, and Wi-Fi congestion - then tells you what it found and why it matters, in language for humans (not sysadmins).

Project status: Early public release, version 0.3.0. The core diagnostic checks are usable now, but results may vary by operating system, network configuration, and permissions. Bug reports and practical feedback are welcome.

Prefer a graphical app?

This repository contains the homenet command-line tool and diagnostic engine. It is a good choice when you want to:

• run checks from a terminal, script, or remote session;
• save machine-readable JSON;
• install a smaller application without a graphical framework; or
• inspect and reuse the diagnostic engine in Python.

If you would rather download an app, click a button, and read the results in a window, use HomeNetCheck. HomeNetCheck sits on top of this homenet code and performs the same core checks. It does not require Python or terminal commands.

You do not need both. For most people who are unfamiliar with terminals, HomeNetCheck is the simpler place to start.

Companion to the book

homenet is a free companion utility for Smart Tech for Real People: Home Networking, which is now available in Kindle and paperback editions. The utility works independently and does not require the book.

• https://www.tartanleaf.com/smart-tech/home-networking/ - the book page
• https://www.tartanleaf.com/smart-tech/ - the Smart Tech series page
• https://www.tartanleaf.com/netcheck/ - the project page (follow for updates)

Installing homenet

homenet is a command-line tool - it runs in a terminal, not a window. You install it once and then run homenet any time you want to check your network.

It needs Python 3.10 or newer on your computer, and a small helper tool called pipx. pipx installs homenet cleanly and keeps it separate from the rest of your system, so it won't interfere with anything else. Three steps:

Step 1 - Check you have Python 3.10 or newer

Open a terminal (see How to open a terminal below) and check your version:

• Windows: py --version
• macOS / Linux: python3 --version

If it prints Python 3.10 or higher (for example Python 3.12.1), you're set - go to Step 2. If it says "command not found" or shows an older version, install Python first:

• macOS: Download the installer from https://www.python.org/downloads/macos/ and run it. Or, if you use Homebrew: brew install python
• Windows: Download from https://www.python.org/downloads/windows/ - during setup, tick the box "Add python.exe to PATH". Or get "Python" from the Microsoft Store.
• Linux: Most distributions already have Python 3.10+. If not, use your package manager. On Ubuntu/Debian: sudo apt update && sudo apt install python3 python3-pip python3-venv

How to open a terminal:

• macOS: Applications → Utilities → Terminal
• Windows: Start menu → type PowerShell (or "Command Prompt") → open it
• Linux: Usually Ctrl+Alt+T, or search for "Terminal"

Step 2 - Install pipx (the installer helper)

First check whether you already have it:

pipx --version

If that prints a version number, skip to Step 3. Otherwise install pipx:

• macOS: brew install pipx then pipx ensurepath - close your terminal and open a new one afterward.
• Windows: pip install --user pipx then python -m pipx ensurepath - close your terminal and open a new one afterward.
• Linux: On Ubuntu/Debian: sudo apt install pipx then pipx ensurepath. On other distributions: pip install --user pipx then python -m pipx ensurepath. Close and reopen your terminal.

Step 3 - Install homenet

With pipx ready, install the published package:

pipx install homenet

That's it - homenet is now available from any terminal.

To install the latest development code instead, use GitHub:

pipx install git+https://github.com/gregweir/Home-Network-Troubleshooter.git

If you downloaded or cloned this source code, open a terminal in its folder and run pipx install ..

Keeping it up to date, and removing it

• Update: pipx upgrade homenet
• Uninstall: pipx uninstall homenet

Requirements

Python 3.10 or newer, pipx, and Git. Works on Linux, macOS, and Windows. Some checks need a working internet connection; homenet degrades gracefully and explains when it can't run something.

Usage

Run every check and read a friendly report:

homenet

Run a single check:

homenet dns
homenet nat          # double NAT
homenet speed
homenet latency

Machine-readable output (great for scripts):

homenet --json
homenet wifi --json

See technical details (timings, raw IPs, counts):

homenet --verbose

Checks

Exit codes

homenet is scriptable:

• 0 - everything looks fine
• 1 - at least one warning
• 2 - a check couldn't run, or a usage error

Privacy and network activity

Most checks run locally. homenet does not change router settings or upload your diagnostic report.

Some tests necessarily contact external services:

• DNS tests resolve example.com and cloudflare.com.
• The public-address test contacts api.ipify.org.
• The optional speed test downloads and uploads test data through Cloudflare's speed-test service.

Results may display your router's local address and your public IP address. Verbose output can contain additional technical details. Review and redact output before posting screenshots or diagnostic reports publicly.

Limitations

homenet is a diagnostic aid, not a replacement for your ISP, router manufacturer, or qualified network support. Speed results are approximate, and Wi-Fi information depends on operating-system support and permissions. homenet reports findings but does not modify network settings.

Support

• Usage help: NetCheck Help
• Project information: NetCheck
• Bugs and feature requests: GitHub Issues

License

MIT - see LICENSE. Free to use, modify, and share.

Author, publisher, and warranty

homenet was developed by Greg Weir and released as free, open-source software by Tartanleaf.com Inc.. It is also a companion utility for Smart Tech for Real People: Home Networking.

This is a community resource, not a supported commercial Tartanleaf product. It is provided under the MIT License without warranty and without a promise of individual support, fixes, or continued development.

See CONTRIBUTING.md for contribution guidance and SECURITY.md for private vulnerability reporting.