Powerful tool for real-time monitoring of LoL (League of Legends) players' activities.
New to Python or unsure what is installed? Follow the Python install walkthrough first.
Install from PyPI:
pip install lol_monitorRun the setup wizard:
lol_monitor --setupThe 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.
- 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.
- 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.
- 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.
- Guided setup: Review and edit settings before saving with
--setup. - Getting started: Use the welcome screen, worked help examples and
--doctorchecks. - Flexible settings: Use config files, dotenv files, environment variables and command-line options.
- Runtime controls: Adjust the running monitor through supported signals.
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.
| I want to... | Run this |
|---|---|
| Configure the target, credentials and alerts | lol_monitor --setup |
| Start monitoring with existing authentication | lol_monitor "<riot_id>" <region> |
| Check authentication, connectivity and one target | lol_monitor --doctor "<riot_id>" <region> |
| Enter or replace securely the Riot API key | lol_monitor --set-riot-api-key |
| Configure and test webhook alerts | Use the setup wizard or follow Webhook Settings |
| Save an SMTP password for email alerts | lol_monitor --set-smtp-password |
| Send a test email | lol_monitor --send-test-email |
| Save a new webhook URL | lol_monitor --set-webhook-url |
| Send a test webhook | lol_monitor --send-test-webhook |
| List recent matches | lol_monitor "<riot_id>" <region> -l -n 10 |
| Write every change to a CSV file | lol_monitor "<riot_id>" <region> -b changes.csv |
| Use a specific configuration and secrets file | lol_monitor --config-file lol_monitor.conf --env-file .env "<riot_id>" <region> |
| List every supported command-line flag | lol_monitor --help |
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.
Full documentation is available at misiektoja.github.io/lol_monitor:
| Page | What it covers |
|---|---|
| Installation | Python walkthrough, PyPI or manual installation, upgrades |
| Setup & First Run | Setup wizard, the Riot API key, region codes, the first monitoring run |
| Configuration | Config file, SMTP, webhooks, storing secrets, check intervals |
| Usage | Monitoring mode, listing mode, notifications, CSV export, signals, terminal output |
| Utility Tools | The CSV format converter and the match history comparison tool |
| Troubleshooting | --doctor preflight checks, what to do when something fails, --verbose and --debug output |
| Testing | Running the offline suite, the linter and the docs build |
| About | Change log, contributing, security, license, support |
See RELEASE_NOTES.md for details.
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.
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.
- misiektoja (@misiektoja)
Licensed under GPLv3. See LICENSE. Dependency licenses are listed in THIRD_PARTY_NOTICES.md.
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.