lol_monitor

Powerful tool for real-time monitoring of LoL (League of Legends) players' activities.

🚀 Quick Install & Run

New to Python or unsure what is installed? Follow the Python install walkthrough first.

Install from PyPI:

pip install lol_monitor

Run the setup wizard:

lol_monitor --setup

The wizard asks for the Riot ID and region, the Riot API key and optional notifications. Review the settings before saving them. See Setup & First Run for how to get the Riot API key and the region codes.

For the manual single-file method, optional dependencies and upgrade commands, see Installation.

Features

🔍 Match Tracking

• Match activity: Detect when a player starts and finishes a game.
• Match reports: Show results, kills, deaths, assists, champion, level, role and lane.
• Game context: Include mode, queue, map, version, both team rosters and champion bans.

📊 Player Insights and Tools

• Ranked statistics: View Solo/Duo and Flex ranks plus top champion mastery.
• Match history: List recent matches and export timestamped reports, including custom games.
• CSV tools: Convert older history files and compare match histories.

🔔 Notifications

• Email alerts: Receive match starts, finishes, summaries, monitoring failures and their recovery.
• Discord and ntfy: Choose webhook events independently from email.
• Champion artwork: Include an optional icon in email, as a Discord thumbnail or as an ntfy attachment.

⚙️ Setup and Configuration

• Guided setup: Review and edit settings before saving with --setup.
• Getting started: Use the welcome screen, worked help examples and --doctor checks.
• Flexible settings: Use config files, dotenv files, environment variables and command-line options.
• Runtime controls: Adjust the running monitor through supported signals.

Common Commands

Use Quick Install & Run above for first-time setup. The table uses PyPI commands. For the manual script equivalents, see Run Individual Commands.

Replace the target placeholders with a Riot ID such as "Player#TAG" plus a region code such as euw1. Monitoring requires the Riot API key described in the setup guide.

Running the tool with no arguments offers the wizard if you have not saved a player. If a player is already saved, it starts monitoring that player.

The tool runs until interrupted (Ctrl+C). Use tmux or screen for persistence and run multiple copies to monitor several players.

For the API key, region codes, saved players and notification setup, see the full Setup & First Run guide.

For email and webhook setup, see Configuration. For notification choices, listing commands and output files, see Usage.

If a run fails, start with Doctor Preflight.

Documentation

Full documentation is available at misiektoja.github.io/lol_monitor:

Change Log

See RELEASE_NOTES.md for details.

Contributing

Bug reports, documentation fixes and code contributions are welcome. See CONTRIBUTING.md for the development setup, the checks CI enforces and what a change needs before it is merged. Participation is covered by the Code of Conduct.

Security

Report a suspected vulnerability privately through GitHub security advisories, never as a public issue. SECURITY.md covers the reporting process, the supported versions and the security posture of stored credentials and configuration loading.

Maintainers

• misiektoja (@misiektoja)

License

Licensed under GPLv3. See LICENSE. Dependency licenses are listed in THIRD_PARTY_NOTICES.md.

Support

Questions, bug reports and vulnerability reports each have a place, listed in SUPPORT.md.

If the project is useful to you, you can support its development through GitHub Sponsors or Buy Me a Coffee.