plane-notify: a Python bot that alerts you when a specific aircraft takes off or lands

It started as one aircraft tracker

The project description is real-time ADS-B notifications for specific aircraft takeoffs and landings, with output to many platforms. The README is more specific about the origin: it was built to track Elon Musk's jet and share its whereabouts, originally on Twitter and later on other platforms after that account was suspended. It has since expanded to run multiple accounts for multiple planes.

The operational reality is that this is a set of scripts at the root of the repository rather than a package. There is `__main__.py` and `__init__.py` at the top level, a `planeClass.py` for the aircraft model, and one module per concern named with a `def` prefix: `defADSBX.py` and `defRpdADSBX.py` for the two ADS-B Exchange paths, `defOpenSky.py` for the free feed, `defDiscord.py`, `defTelegram.py` and `defMastodon.py` for output, `defMap.py` and `modify_image.py` for the map image, `defAirport.py` for reverse coordinate lookup, and `defSS.py` for screenshot output.

The README states the origin of the location data too: takeoff and landing locations come from reverse lookup of coordinates. It also says the algorithm is documented separately in `PseudoCode.md`, and further references sit in `References.md`.

Choosing a data source is the first real decision

The program polls either OpenSky, which is free, or ADS-B Exchange, which is paid. The README's guidance on this is specific enough to be useful.

The OpenSky API is free for everyone, but the data is stated to be not as good as ADS-B Exchange. The ADS-B Exchange API is not free, the program will not work with the RapidAPI offering, and it only works with the API provided under a partnership arrangement. The README warns the full API is not cheap and says not to contact them unless ready to pay.

Two further constraints appear. If you set up multiple aircraft and use ADS-B Exchange as the source, you must have `/all` endpoint access or it will not work. And the author notes there are more bugs when using OpenSky, because the main development effort went into the ADS-B Exchange implementation.

There is also an optional proxy, pointed at a project called lemonodor, recommended when running several instances against ADS-B Exchange so as not to abuse the API, and left disabled otherwise. A separate line asks contributors to add RapidAPI support if they want it. The topics list the aviation side of the domain: `ads-b`, `acas`, `tcas`, `squawk`, `emergency-squawk`, `resolutionadviosry`, `takeoff` and `land`.

Install is pipenv plus screen, or one compose command

The non-Docker path starts with the standard Debian package installs, then Pipenv:

pip install pipenv
pipenv install

Dependencies come from a committed `Pipfile` and `Pipfile.lock`, so the install is reproducible if you use the lock file. The next requirement is either Selenium with ChromeDriver or Google Static Maps. Selenium with Chrome is used to take a screenshot of the plane on a globe site; Google Static Maps is the alternative and the README warns it can cost money if overused. On Debian the Chrome repository is added and `google-chrome-stable` installed.

The program is expected to run in a background session, which is why `screen` is in the install list:

screen -R <name screen whatever you want>

Cloning is pinned to a branch that is not the obvious default:

git clone -b multi --single-branch https://github.com/Jxck-S/plane-notify.git
cd plane-notify

The Docker route is one command from the repository root, `docker-compose up -d`, with logs read through `docker logs CONTAINER`. The compose file pins `platform: linux/amd64`, sets `shm_size: 2gb`, and bind-mounts the working directory into the container, which means config edits do not require a rebuild. The `Dockerfile` builds from `python:3.14`, installs Chrome and `python3-dev`, then runs `pipenv install --deploy` before launching `__main__.py`.

One INI file per aircraft, and a main config for keys

Configuration is split in two. A `mainconf.ini` holds the keys and URLs, and is created by copying `mainconf.ini.example`. Each aircraft gets its own file in the `configs/` directory, created from `plane1.ini.example`, and the program picks up any file in that folder ending in `.ini`. The README notes the filename can change as long as the `.ini` extension stays, and that each plane should have its own config.

Output methods are configured in the aircraft config, which is where the choice between the Selenium screenshot and the static map image is made.

The Telegram output has its own documented setup, added in March 2022. You create a bot through BotFather with `/newbot` and receive a token for the HTTP API. To find the destination chat, channel or group identifier, the README describes forwarding a message to JsonDumpBot and reading the `forward_from_chat` id from its JSON reply, or opening Telegram web and reading the group identifier out of the URL. The bot needs to be added as an administrator in a channel for messages to be sent.

There is more here than notifications. `aircraft_type_fuel_consumption_rates.json` alongside `fuel_calc.py` and `calculate_headings.py` suggest the tool also estimates fuel burn between events and computes headings, which is a more unusual addition than the notification framing suggests.

The TODO list is the clearest statement about maturity

The README carries a TODO section, and its first entries are structural rather than feature requests: general cleanup, restructuring the project because it is currently random files, adding proper logging and a service to run the program, and removing excessive printing. It also proposes a single config YAML file, or a database, to replace the current per-aircraft INI approach.

The contributing section is equally candid. The author writes that there are many better ways to improve the program and better ways to make it work properly, describes himself as a noob, and invites pull requests and discussion on the project's Discord server.

There are no tagged releases at all, which is worth pairing with that TODO list. With 2,547 stars, 422 forks and 10 open issues the project is not abandoned: the repository is not archived and the last push was recorded on 2026-09-15. It is GPL-3.0 licensed with a `LICENSE` file in the tree.

What the repository does have is breadth of output. Discord, Telegram and Mastodon each get their own module, and the `ExImages/` directory holds example outputs. For someone who wants a departure notification pushed to three different networks from one INI file, that breadth is the feature.

Editorial conclusion

plane-notify is a notification tool with a narrow and specific job, and it does that job across several output platforms without requiring an account anywhere. The README says plainly that the project layout is currently random because the author did not know how to structure a project, and the TODO list confirms restructuring is in progress, so judge it as a working script rather than a library. Two practical decisions come first. The OpenSky source is free but the author states its data is worse and the implementation has more bugs, while ADS-B Exchange needs a paid partnership API and specifically will not work through their RapidAPI tier. For a first run, start with OpenSky, one aircraft INI file and the Discord output.

Frequently asked questions

Official sources

1. Issues
2. Jxck-S/plane-notify on GitHub
3. License: GPL-3.0
4. Project website
5. README