Installing

Fathom consists of 3 parts. Here’s how to install each one.

Commandline Tools

Fathom’s commandline tools take your labeled pages as input and train the machine-learning model. They also contain an embedded copy of FathomFox (see below), the simplest way to collect pages. If you don’t already have Python 3.7 or better, download it from https://www.python.org/downloads/. Then, install the tools by running…

pip3 install fathom-web

It’s possible your Python package manager is called simply “pip” rather than “pip3”. Give that a try if the above fails.

You will also need to install Node.js to use many of the commandline tools.

FathomFox

FathomFox is a browser extension used to label web pages. The best way to get it is to first install the commandline tools and then run…

fathom fox

This will launch a built-in copy of FathomFox in a fresh Firefox profile so ad blockers and other customizations don’t interfere with the clean capture of labeled pages. (Some ad blockers will make changes to the DOM, like adding style attributes to ad iframes to hide them.) Using the commandline launcher also lets you pass in your own rulesets for debugging with the FathomFox Evaluator. See the -r option on the fathom fox reference page.

For more casual use, you can instead install FathomFox through the web, in which case it will be your responsibility to avoid addons that might mutate the DOM.

Fathom

Fathom proper is a JS library which runs trained rulesets to do the actual recognition. You don’t need to worry about installing it until your rulesets are performing satisfactorily and you’re ready to integrate them with your application.

If your application runs server-side under Node.js, you can install the Fathom node package like any other dependency:

npm install fathom-web

If, instead, you’re working on a Firefox feature, you can use the copy of Fathom already in Firefox by saying something like this at the top of the file containing your ruleset:

ChromeUtils.defineModuleGetter(
  this,
  "fathom",
  "resource://gre/modules/third_party/fathom/fathom.jsm"
);

const {
  dom,
  element,
  out,
  rule,
  ruleset,
  score,
  type,
  utils: { identity, isVisible, min },
  clusters: { euclidean },
} = fathom;

Finally, if you need a self-contained bundle of Fathom in a context that can’t use node packages, check out our source and run make -C fathom bundle. This creates the bundle at fathom/dist/fathom.js.