Skip to content

Installation

GitHub Monitor runs as a local Python program. Choose the PyPI package for the shortest command or the manual script to run a downloaded file.

New to Python? Start with New to Python: check and install.

Requirements

  • Python 3.10 or higher
  • Libraries: PyGithub, requests, urllib3, python-dateutil, pytz, tzlocal, python-dotenv
  • Optional for display-width-aware terminal truncation with TRUNCATE_CHARS: wcwidth
  • Optional for better coloured output in the classic Windows Command Prompt: colorama. --doctor reports it as missing only on Windows, where it makes a difference

Tested on:

  • macOS: Tahoe, Sequoia, Sonoma, Ventura
  • Linux: Raspberry Pi OS (Trixie, Bookworm, Bullseye), Ubuntu 24/25, Rocky Linux 8.x/9.x, Kali Linux 2026/2025/2024
  • Windows: 11, 10

It should work on other versions of macOS, Linux, Unix and Windows as well.

New to Python: check and install

Use this section if you are new to Python or do not know what is already installed. The platform sections only prepare Python and pip. Everyone then uses the same GitHub Monitor installation and setup commands. GitHub Monitor requires Python 3.10 or newer.

Check whether GitHub Monitor is already installed

Open Windows PowerShell on Windows or Terminal on macOS and Linux then run:

github_monitor --version

If this prints a GitHub Monitor version, skip to Run the setup wizard. If the command is not recognized or not found, continue with the section for your operating system.

Windows 10 or 11

Open Windows PowerShell. Select Start, type PowerShell then open Windows PowerShell.

Check Python and pip:

python --version
pip --version

If both commands work and Python reports version 3.10 or newer, skip to Install GitHub Monitor.

If either command fails or Python is older than the required version:

  1. Open the official Python Install Manager in Microsoft Store, select View in Store then select Install. If Microsoft Store is unavailable, download the manager from python.org.

  2. Close PowerShell then open it again.

  3. Run py install default to install the default Python release then run python --version. If an older installation still takes precedence, use the troubleshooting guide below to correct the command aliases.

  4. Check both commands again:

    python --version
pip --version

If pip is still not recognized, run py install --refresh, close PowerShell then open it again. This Python Install Manager command repairs its command aliases.

See the official Python Install Manager troubleshooting table if either check is still unavailable.

macOS

Open Terminal. Press Command+Space, type Terminal then press Return.

Check Python and pip:

python3 --version
pip --version

If both commands work and Python reports version 3.10 or newer, skip to Install GitHub Monitor.

If either command fails or Python is older than the required version:

  1. Open the official Python downloads for macOS. Select a stable Python release that meets the requirement above then download its macOS 64-bit universal2 installer. This single installer supports Apple Silicon and Intel Macs.

  2. Open the downloaded .pkg file. Keep the standard options, select Continue through the installer then enter your macOS password when requested.

  3. Open the new Python 3.x folder for the version you installed in Applications then double-click Install Certificates.command. Wait until its Terminal window reports update complete then close that window.

  4. Close Terminal then open it again.

  5. Check both commands again:

    python3 --version
pip --version

The official Using Python on macOS guide shows every installer screen and explains the installed applications.

Ubuntu, Debian, Raspberry Pi OS or Kali

Open Terminal then check Python and pip:

python3 --version
pip --version

If both commands work and Python reports version 3.10 or newer, skip to Install GitHub Monitor.

If either command fails or Python is too old, install or update the packages:

sudo apt update
sudo apt install python3 python3-pip

The package manager keeps an existing current package instead of reinstalling it. Terminal may ask for your password. Type the password you use to sign in then press Enter. Terminal does not show password characters while you type.

Check both commands again:

python3 --version
pip --version

If Python reports a version older than 3.10, follow your distribution's instructions to install a supported Python version before continuing. For another Linux distribution, install Python 3.10 or newer plus pip through its package manager.

Install GitHub Monitor

Every operating system uses the same command:

pip install github_monitor

Verify the installation:

github_monitor --version

On Linux, pip may report that the system Python is externally managed. If that happens, install GitHub Monitor with the isolated pipx tool instead:

sudo apt install pipx
pipx ensurepath
pipx install github_monitor

Close Terminal, open it again then run github_monitor --version.

Run the setup wizard

Every operating system uses the same command:

github_monitor --setup

The setup wizard collects the target, service credentials and optional notifications. Continue to Setup & First Run for a walkthrough of its questions.

Choose an Installation Method

Method Best for Command used in later examples
PyPI Users who already have Python or followed the beginner steps above github_monitor [OPTIONS]
Manual script Users who want to download and run one Python file python3 github_monitor.py [OPTIONS] on macOS/Linux or python github_monitor.py [OPTIONS] on Windows

Later pages use the short PyPI command. If you chose the manual script, keep the options after github_monitor and replace the command itself with the one in the table. The setup wizard and --help also print commands for the detected installation.

Install from PyPI

pip install github_monitor
github_monitor --version

Install the Manual Script

Download the script and dependency list into the same directory:

curl -fsSLO https://raw.githubusercontent.com/misiektoja/github_monitor/refs/heads/main/github_monitor.py
curl -fsSLO https://raw.githubusercontent.com/misiektoja/github_monitor/refs/heads/main/requirements.txt

You can also download github_monitor.py and requirements.txt in a browser or use the files from a cloned repository.

Install the core dependencies:

pip install -r requirements.txt

You can install the core dependencies directly if you downloaded only the script:

pip install PyGithub requests urllib3 python-dateutil pytz tzlocal python-dotenv

Verify the script:

python3 github_monitor.py --version

Use python github_monitor.py --version on Windows.

Next Step

Continue to Setup & First Run to prepare credentials, choose a target and run the wizard.

Upgrading

Use the same installation method and Python environment you used originally. Upgrading does not remove your configuration, .env secrets, logs, CSV files or saved history. Keep those files in the same working directory or another persistent location.

Upgrade a PyPI Installation

pip install --upgrade github_monitor
github_monitor --version

If you used pipx, upgrade with:

pipx upgrade github_monitor

Upgrade a Manual Installation

Replace github_monitor.py and requirements.txt with the newest copies. You can download them in a browser, use the files from an updated clone or run:

curl -fsSLO https://raw.githubusercontent.com/misiektoja/github_monitor/refs/heads/main/github_monitor.py
curl -fsSLO https://raw.githubusercontent.com/misiektoja/github_monitor/refs/heads/main/requirements.txt
pip install --upgrade -r requirements.txt
python3 github_monitor.py --version

Refresh the dependencies even when requirements.txt appears unchanged because a new release may add or change a required library.

Use python github_monitor.py --version on Windows. If you modified the script itself, save your changes before replacing it and reapply them to the new version.

Check Upgrade

After any upgrade run the doctor command:

github_monitor --doctor <github_target>

Use the manual equivalent if you installed the script directly.