Torrent scraping and geolocation tool
Add shell completion generation
Add author/license information to README
Hotfix default directory creation



You can also use your local clone with git send-email.


Torrentmap is a CLI tool used to generate a world heatmap of torrent popularity.

It maintains an internal database of known torrents and known peers , which is then used to geolocate the peers and draw a colored map of the world.


To install trmp into currently active Python environment run pip install . in the project root.

For development use Poetry with poetry install.


usage: trmp [-h] [-d DIR] [-ll LOGLEVEL] [-lf LOGFILE] {list,update,add,remove,map} ...

Torrent mapping utility.

Analyzes popularity of known torrents by country/genre.

positional arguments:

  -h, --help            show this help message and exit
  -d DIR, --dir DIR     Path to working directory (default ~/.local/share/trmp)
  -ll LOGLEVEL, --loglevel LOGLEVEL
                        Logging vebosity (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  -lf LOGFILE, --logfile LOGFILE
                        Log file (defaul /dev/stderr)

In order to add *.torrent files to storage directory run trmp add:

usage: trmp add [-h] FILE [FILE ...]

Add new torrent files to the database. Note that peers will only be obtained after an
update is issued.

positional arguments:
  FILE        Torrent file(s) to add to the database

    -h, --help  show this help message and exit

Once the torrents are added their summary will be printed to standard output. Note that no peers will be shown at this point - run trmp update to announce to trackers and get peers.

usage: trmp update [-h] [-g] [HASH ...]

Update torrent peer list and geolocate unknown peers. This command
requires network connectivity.

positional arguments:
  HASH             Torrent infohash(es) to update (default all)

  -h, --help       show this help message and exit
  -g, --geolocate  Do not ask for new peers, only geolocate existing ones.

View the torrent details, including peers, with trmp list. It uses JSON as output format and can be easily saved to a file.

usage: trmp list [-h] [-p] [-t] [HASH ...]

List known torrents in a JSON format. By default all torrents and all
peers are listed - use appropriate switches to list only peers or torrents
without peers.

positional arguments:
  HASH            Torrent infohash(es) to use when listing (default all)

  -h, --help      show this help message and exit
  -p, --peers     List only peers, without torrents
  -t, --torrents  List only torrents, without peers

At any point you may remove one of the torrents with trmp remove

usage: trmp remove [-h] HASH [HASH ...]

Remove torrents with given hashes. This may or may not be equivalent to
removing infohash files from the working directory. All associated peers
will be fogotten, unless they participate in another known torrent.

positional arguments:
  HASH        Torrent infohash(es) to remove from the database ('ALL' to
              remove all)

  -h, --help  show this help message and exit

To visualize the peer distribution use trmp map. By default the generated map will be saved to a PDF file in $PWD.

usage: trmp map [-h] [-f FILENAME] [-t] [HASH ...]

Draw the heatmap of known torrents using GeoPandas.

positional arguments:
  HASH                  Torrent infohash(es) to map (default all)

  -h, --help            show this help message and exit
  -f FILENAME, --filename FILENAME
                        Map file name override (default 'map-{ISO
  -t, --torrents        Annotate the map with a list of used torrents.

See below for an example map, generated with some popular Linux ISO torrents.

Example map of Linux ISO torrent popularity

#Feature wishlist

  • [x] CLI interface
  • [x] obtaining IPs from HTTP trackers
  • [x] obtaining IPs from UDP trackers
  • [x] geolocating IPs
  • [x] generating a map of torrent popularity
  • [ ] sane error handling


Copyright 2023 Piotr Machura

Source code repository: https://git.sr.ht/~piotr-machura/torrentmap

Distributed under GNU General Public License version 2.