connmap plots your live network peers on a world map from an X11 widget

A widget that turns the connection table into a map

The idea is small and immediately legible. connmap is an X11 desktop widget that shows the location of your current network peers on a world map, in real time, and the README notes in parentheses that it works on Wayland as well. Note that the clone URL in the readme points at h2337/connmap rather than the repository this documentation lives in, so follow the URL the readme gives rather than the repository name. The mechanism has two halves. The first is reading the machine's current network connections, which is where the iproute2 runtime dependency comes from, since the connection table is what the widget polls on its update interval. The second is resolving each peer's location and drawing it on a map, which is what the cairo drawing and the bundled GeoLite2 data are for. The result is a small window pinned anywhere on the desktop that fills with dots wherever your traffic is coming from. The people who want this are the ones who find a server log interesting, and the closest comparison is a weather widget for your traffic, which is exactly the register it is aiming at.

The build is clone, make install, run the elf

Installation is a sequence of steps you can do in one terminal session. You clone the repository with git clone https://github.com/h2337/connmap --depth 1, install the dependencies listed below, run make install, and then run the resulting executable./connmap.elf. If you want it to run without attaching to the terminal, add an ampersand at the end of the command, so./connmal.elf &, and the documentation notes that the executable name is spelled that way in the example. On i3wm you can also add it to your config so it starts with the session, which makes sure the widget is in your PATH.

exec --no-startup-id connmap.elf

The Makefile is a plain hand-written one, and it tells you the shape of the project. The compiler is gcc with a gnu11 standard, the include path is the includes directory, and the libraries are pulled in through pkg-config for cairo, x11 and xfixes, with the maths library linked too. The sources are found by a find over the sources directory for.c files, and the objects land in a build directory, or build/debug when the debug target is used, which adds -O0 -ggdb and a DEBUG define and produces a separate connmap.debug.elf binary. There is no configure step and no autotools, which is pleasant for a project of this size.

Dependencies are small, and the install target unzips the map data

The dependency list is short and split by build, installation and runtime. Build dependencies are xlib, libxext, libxfixes and libcairo2. Installation dependencies are unzip. Runtime dependencies are iproute2. The unzip entry is explained by what the install target does, since the make install recipe unzips an archive of the IP to country mapping data into the resources directory, and then copies the connmap directory into your configuration directory. The distributions are covered with one command each.

sudo pacman -S --needed iproute2 libx11 libxext libxfixes cairo unzip

sudo apt install iproute2 libx11-dev libxext-dev libxfixes-dev libcairo2-dev unzip

Note the difference between the two, since the Debian package names carry the -dev suffix because they ship headers as well as libraries, while the Arch packages are the runtime libraries that the pkg-config call resolves against. The X libraries are not optional decoration, because xfixes is what lets the widget track the window and the screen, which is also why the map can be dragged around and why the documentation mentions that dragging only works in a desktop environment that does not treat mouse drag as a multi-select gesture.

The config file is five lines and controls the whole widget

Installation creates a configuration file at ~/.config/connmap/connmaprc, and the default looks like this.

location_x 20
location_y 500
map_width 1000
black false
update_interval 1

Each key does one thing. The location_x and location_y pair sets the initial widget position on the desktop, and the documentation notes you can drag and drop the widget later with the mouse if your desktop environment does not treat mouse drag as a multi-select. The map_width key sets a custom pixel width for the map, with the height calculated automatically as width divided by two, so a width of 500 gives a 500 by 250 pixel map and a width of 2000 gives 2000 by 1000. Setting black to true draws the map outline in black rather than white, which is the difference between a legible widget and an invisible one on a dark themed desktop. The update_interval is the number of seconds the application sleeps before fetching the updated list of network connections, and at the default of one second the map is effectively live.

GeoLite2 is bundled, which is a licensing fact you should read

The data behind the map is where the legal weight sits, and the README puts it in the License section rather than burying it. The product includes GeoLite2 Data created by MaxMind, available from maxmind.com, and the project itself is MIT-licensed. Those are two different statements and they need to be kept apart. The code is MIT. The geolocation database that ships with it comes from MaxMind under MaxMind's own terms, which is why the attribution line is printed in the readme rather than left implicit. The Makefile shows the practical side of it, since the install target unzips an archive named ipv4.csv.zip into the resources directory and the clean target removes the extracted ipv4.csv. The name of that file is a good reminder that this is a lookup table mapping addresses to locations, built once at install time.

Only IPv4 and only i3wm, and the README says both

The Limitations section is two bullets and both matter. The first is that it has been tested only with i3wm and might not work as expected in other desktop environments or window managers, which is a stronger statement than untested. The second is that only IPv4 is supported. That second one is a real constraint rather than a missing feature, because the whole pipeline depends on an address to country mapping and the bundled data is named ipv4.csv. An IPv6-only host, or a network that has moved to IPv6, is simply outside what the widget can show. The i3wm limitation is softer, since the widget is X11 and the README says it works on Wayland too, but the specific behaviours the widget relies on, such as dragging the window and having it not steal focus, are the ones i3 provides, and a desktop with a full window manager may fight it. The honest reading is that this is a tool built for one desktop setup and extended to others, and the configuration file gives you no way to change the display server behaviour.

Where connmap is the wrong choice

The first wrong case is a network you need to actually understand rather than glance at, because the widget shows you where a peer is and not what it is doing, so a DDoS or a scraping run looks like a cluster of dots. The second is IPv6, covered above. The third is a machine where the traffic is not yours, such as a router or a container host, since the widget reads the local connection table and therefore only shows the peers of the machine it runs on, which on a gateway is not the peers you care about. The fourth is a user who wants history, because the widget is a live view of the current connections and nothing in the documentation describes storing past samples, so the map is a present-tense picture and not a record. The fifth is anyone who needs the peer to be a machine rather than a person, since the display is a map of locations, and a corporate egress IP and a home connection in the same city are indistinguishable on it. A conventional network monitor answers those questions; this one answers the different question of where in the world the connections are coming from.

Editorial conclusion

Linux desktop users who like watching traffic arrive, particularly on i3 where a floating widget fits the way the window manager works, are the people connmap is for, and the fact that it needs no account, no API key for the map and no configuration beyond five lines makes it a five minute install. It is the wrong tool for anything IPv6, since the documentation states only IPv4 is supported, and it is the wrong tool for a desktop environment other than i3wm, since it has been tested only there and might not work as expected elsewhere. Check three things before you rely on it: that the network connections you care about are visible in the tool's own view of the connection table, since the runtime dependency is iproute2 and the widget shows what that view reports, that the GeoLite2 data it uses is acceptable for your purposes, since the product includes GeoLite2 Data created by MaxMind, and that the update interval you choose is not going to cost you more CPU than the map is worth. The licence is MIT, the repository publishes no GitHub releases, and the last push was on 2026-06-13.

Frequently asked questions

Official sources

1. cantrepro/connmap on GitHub
2. Issues
3. License: MIT
4. README