Ways to run NetMap (including without cloning the repo)¶

Short answer: yes. You don't need git or to clone anything. The easiest way today is to download the ZIP from GitHub and double-click the launcher. For people who only need to look at results, send them the offline HTML report: it needs no install at all.

flowchart TD
    Q{"What does the person want?"}
    Q -->|"Just view results"| R["① Send the offline HTML report<br/>no install at all"]
    Q -->|"Run NetMap themselves"| P{"Do they have Python 3.9+?"}
    P -->|"yes / can install it"| Z["② Download ZIP → double-click launcher<br/>✅ works today, recommended"]
    P -->|"comfortable with a terminal"| X["③ pipx straight from GitHub<br/>needs packaging work first"]
    P -->|"no Python, non-technical"| E["④ Standalone app (.exe / .app)<br/>best for common users, needs a build"]
    Q -->|"Developer / server"| D["⑤ Docker<br/>files only on Mac/Windows"]
    Q -->|"No computer access, just a browser"| C["⑥ GitHub Codespaces<br/>files and sample only"]

Comparison¶

#	Method	Works today?	User needs	Live capture	Effort for a common user
①	Offline HTML report	✅ Yes	A browser	— (results only)	⭐ Easiest
②	Download ZIP + launcher	✅ Yes	Python 3.9+	✅ macOS, Linux, Windows (with Npcap)	⭐⭐ Easy
③	`pipx run` from GitHub	❌ Needs a `pyproject.toml`	Python + pipx	✅	⭐⭐⭐ Terminal users
④	Standalone app (PyInstaller)	❌ Needs a build per OS	Nothing	✅ (Windows needs Npcap)	⭐ Easiest to run
⑤	Docker	❌ Needs a Dockerfile	Docker	Linux hosts only	⭐⭐⭐⭐ Developers
⑥	GitHub Codespaces	✅ Yes	GitHub account, browser	❌ (cloud VM)	⭐⭐⭐

Anyone with a browser can explore a capture you've already analyzed. To simply show someone NetMap, send them the live demo on the project website: it's this same report, built from the sample captures.

In NetMap: Export → Interactive report. Or from the CLI: python main.py capture.pcapng, which writes capture_report.html.
Send that single .html file by email, chat or Google Drive.
The recipient double-clicks it. They get the full map, charts, hosts, alerts and DNS panels. It needs internet only for the map background and libraries.

An example is in examples/sample-output/sample-browsing_report.html.

The report contains the IP addresses and site names from the capture. Only share captures you're comfortable making public.

② Download ZIP and double-click (recommended, works today)¶

This doesn't need git, and the launcher installs everything else itself.

Install Python 3.9 or newer if needed:
macOS: usually already there. If not, run xcode-select --install or use python.org.
Windows: python.org. Tick "Add python.exe to PATH" in the installer. For live capture, also install Npcap (Wireshark includes it).
Linux: sudo apt install python3 python3-venv (or your distro's equivalent).
Open the repo page on GitHub → green Code button → Download ZIP. Or download this link directly: https://github.com/praneeth132006/Network-Tracking-Using-Wireshark-And-Google-Maps/archive/refs/heads/main.zip
Unzip it anywhere.
Start it:
macOS: double-click NetMap.command. The first time, macOS may block it: right-click → Open → Open.
Windows: double-click start.bat.
Linux: run ./run_dashboard.sh in a terminal.
The first start takes about a minute (it creates a private .venv and installs packages). After that, NetMap opens at http://127.0.0.1:5050.

Making it even easier: if you create a GitHub Release (Releases → Draft a new release → tag v2.0.0), GitHub attaches the ZIP automatically. You can then share one stable link: https://github.com/praneeth132006/Network-Tracking-Using-Wireshark-And-Google-Maps/releases/latest.

③ One command with pipx (needs packaging first)¶

For people comfortable with a terminal, the nicest experience would be:

pipx run --spec git+https://github.com/praneeth132006/Network-Tracking-Using-Wireshark-And-Google-Maps.git netmap

That downloads, installs into a throwaway environment and starts NetMap, with no clone and no cd. This doesn't work yet. It needs:

a pyproject.toml declaring the dependencies and a netmap console command
the modules moved into a package (e.g. netmap/) so templates/, static/, GeoLiteCity.dat and capture_helper.py are included as package data
BASE_DIR pointing at the package folder (already done via __file__). Uploaded and exported files already go to the temp folder or the browser, so nothing needs to be written inside the install.

After that, publishing to PyPI would shorten it to pipx run netmap-geo. Note that the name netmap may already be taken on PyPI.

④ Standalone app: best for non-technical users (needs a build)¶

PyInstaller can bundle Python, all the libraries, the GeoIP database and the UI into one download per OS: NetMap.exe on Windows, NetMap.app on macOS. Users then don't need Python at all. They download, double-click, and done.

Things to know: - It has to be built on each OS (a GitHub Actions workflow can build all three and attach them to a Release). - The download is about 60–100 MB because of Python and Scapy. - The macOS app should be code-signed and notarized (needs a paid Apple Developer account). Otherwise users see "unidentified developer" and must right-click → Open. - The live-capture helper currently runs the system Python as root (because of macOS privacy rules). A frozen app would need the helper bundled as its own small executable. - Windows users still need Npcap for live capture. Opening files works without it.

This is the best long-term option for common users, and the most work.

⑤ Docker (developers)¶

A Docker image works everywhere Docker runs, with no Python setup:

docker run --rm -p 5050:5050 netmap      # (once an image exists)

Limitation: Docker on macOS and Windows runs inside a Linux VM, so the container can't see your real network card. Live capture only works on Linux hosts (with --net=host --cap-add=NET_RAW --cap-add=NET_ADMIN). On Mac and Windows it's useful only for opening capture files. It needs a Dockerfile, which isn't in the repo yet.

⑥ GitHub Codespaces (just a browser)¶

On the repo page: Code → Codespaces → Create codespace. In its terminal:

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt && .venv/bin/python app.py --host 0.0.0.0

Codespaces forwards port 5050 to a private URL. Use the sample and upload features; live capture would only see the cloud VM's own traffic. The free tier includes a monthly allowance of hours.

Recommendation¶

Audience	Use
Teachers, evaluators, friends who just want to see results	① HTML report
Classmates and common users who want to try it	② ZIP + double-click, ideally from a GitHub Release link
Long-term "download and run" for anyone	④ Standalone app: the next project milestone