Skip to content
A list of Mastodon Instances, Described
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Described Instance List Tools

This is a set of tools for generating information, including descriptions, on every listed Mastodon instance, in various formats, like sqlite and html.


chmod +x && Look in the data/ directory for your generated files.


Oh wow, library errors? This is may be why. You need:

  • Python 3
  • pip3 install bs4 BeautifulSoup, for parsing HTML
  • pip3 install requests, for downloading websites without silly syntactic junk
  • pip3 install cheetah3, for generating html

The Scripts

Script Effect output file
tools/ downloads and generates .json database data/DescribedInstances.json
tools/ generates a markdown file from the .json database, above data/
tools/ generates two HTML files from .json file, above data/DescribedInstances.html
tools/ generates an sqlite database of the .json file, above data/DescribedInstances.sqlite generates all of the above data/*
tools/ delivers the json descripton for a single instance none


These tools are ad hoc kludges to get the job done only. This is a simple one-shot tool that you can run for 30 minutes to consume all the info out there. I may turn this into a more interruption-friendly database updater later.


To generate all files, simply:

chmod +x && ./

To generate each file individually:

cd tools
python3 ../data/DescribedInstances.json
# wait about 30 minutes for stuff to download
python3 ../data/DescribedInstances.json ../data/
python3 ../data/DescribedInstances.json ../data/DescribedInstances
python3 ../data/DescribedInstances.json ../data/DescribedInstances.sqlite

This is pretty much what the script does.

About This Instance

To see a json file describing an instance, try


This might be more useful than the monolithic approach above.


To test a smaller set of random instance data, set the TEST=1 environment variable, e.g.:

TEST=1 ./


cd tools/
TEST=1 python3 federation2json my_testdata.json

To update a previous .json file, skipping the instance list download from

JSON_FILE=data/DescribedInstances.json ./

Since you read this README all the way to the end, have a gift:


Play nice! Cheers.

You can’t perform that action at this time.