Metadata-Version: 2.4
Name: instagram_monitor
Version: 3.2
Summary: Track Instagram users' activities, profile changes and capture content with beautiful dashboards and instant notifications
Author-email: Michal Szymanski <misiektoja-pypi@rm-rf.ninja>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/misiektoja/instagram_monitor
Project-URL: Source, https://github.com/misiektoja/instagram_monitor
Project-URL: Changelog, https://github.com/misiektoja/instagram_monitor/blob/main/RELEASE_NOTES.md
Keywords: instagram,monitoring,tracking,real-time,osint,instaloader
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: instaloader>=4.15.1
Requires-Dist: requests>=2.0
Requires-Dist: python-dateutil>=2.8
Requires-Dist: pytz>=2020.1
Requires-Dist: tzlocal>=4.0
Requires-Dist: python-dotenv>=0.19
Requires-Dist: tqdm>=4.0
Requires-Dist: flask>=2.0
Requires-Dist: rich>=12.0
Requires-Dist: colorama>=0.4.6; platform_system == "Windows"
Dynamic: license-file

# instagram_monitor

<p align="left">
  <img src="https://img.shields.io/github/v/release/misiektoja/instagram_monitor?style=flat-square&color=blue" alt="GitHub Release" />
  <img src="https://img.shields.io/pypi/v/instagram_monitor?style=flat-square&color=teal" alt="PyPI Version" />
  <img src="https://img.shields.io/github/stars/misiektoja/instagram_monitor?style=flat-square&color=magenta" alt="GitHub Stars" />
  <img src="https://img.shields.io/badge/python-3.9+-blueviolet?style=flat-square" alt="Python Versions" />
  <img src="https://img.shields.io/github/license/misiektoja/instagram_monitor?style=flat-square&color=blue" alt="License" />
  <img src="https://img.shields.io/github/last-commit/misiektoja/instagram_monitor?style=flat-square&color=green" alt="Last Commit" />
  <img src="https://img.shields.io/badge/maintenance-active-brightgreen?style=flat-square" alt="Maintenance" />
</p>

Powerful, real-time OSINT suite for tracking every activity on Instagram - from story updates and bio changes to follower shifts, providing stunning dashboards and instant alerts to keep you in the loop.

### 🚀 Quick Install

Python
```sh
pip install instagram_monitor
```

Docker
```sh
docker pull misiektoja/instagram-monitor:latest
```

<p align="center">
   <img src="https://raw.githubusercontent.com/misiektoja/instagram_monitor/refs/heads/main/assets/instagram_monitor_web_dashboard.png" alt="instagram_monitor_web_dashboard_screenshot" width="100%"/>
</p>

<a id="features"></a>
## Features

### 🔍 Real-time Tracking
- **Profile Activity**: Monitor **new posts, reels** and **stories** in real-time.
- **Audience Insights**: Track changes in **followings** and **followers**.
- **Visual Changes**: Detect updates to **profile pictures** and **visibility** (public/private).
- **Bio Updates**: Stay informed about changes to **user bio**.

### 📥 Media Download
- **Anonymous Stories**: Download story images and videos **without leaving traces**.
- **High-Quality Media**: Save post images, reel videos and profile pictures.
- **Batch Support**: Monitor and download media for **multiple users simultaneously**.

### 📱 Interactive Dashboards
- **Terminal Dashboard**: Beautiful, live-updating CLI interface with real-time stats.
- **Web Dashboard**: Modern, local web UI with activity feeds and remote controls.
- **Image Support**: View profile pictures and media directly in your terminal (via `imgcat`).

### 🔔 Smart Notifications
- **Multi-Channel**: Instant alerts via **Email** and **Webhooks** (**Discord** etc.).
- **Rich Alerts**: Attached media (profile pics, stories, posts) directly in notifications.
- **Error Reporting**: Be notified if the monitoring process hits a snag.

### 🛡️ Privacy & Detection Avoidance
- **Be Human Mode**: Simulates random user actions to blend in.
- **Jitter Mode**: Adds human-like delays to HTTP requests.
- **Hour-Range Checking**: Limits activity to specific hours of the day.
- **Account Flexibility**: Works with or without a logged-in Instagram account.

### ⚙️ Power Features
- **CSV Logging**: Log all activities and profile changes with timestamps.
- **Flexible Config**: Support for files, dotenv and environment variables.
- **Follower Churn**: Detailed tracking of exactly who followed or unfollowed.
- **Remote Control**: Manage tracking features via signals or the web UI.
- **Docker Ready**: Run via Docker Hub image or local image build with persisted config, dotenv and sessions.

<p align="center">
   <img src="https://raw.githubusercontent.com/misiektoja/instagram_monitor/refs/heads/main/assets/instagram_monitor_terminal_dashboard.png" alt="instagram_monitor_terminal_dashboard" width="100%"/>
</p>

<p align="center">
   <img src="https://raw.githubusercontent.com/misiektoja/instagram_monitor/refs/heads/main/assets/instagram_monitor.png" alt="instagram_monitor_log_screenshot" width="100%"/>
</p>

<a id="table-of-contents"></a>
## Table of Contents

1. [Requirements](#requirements)
2. [Installation](#installation)
   * [Install from PyPI](#install-from-pypi)
   * [Install from Docker Hub](#install-from-docker-hub)
   * [Manual Installation](#manual-installation)
   * [Upgrading](#upgrading)
3. [Quick Start](#quick-start)
4. [Configuration](#configuration)
   * [Configuration File](#configuration-file)
   * [Session Mode 1: Without Logged-In Instagram Account (No Session Login)](#session-mode-1-without-logged-in-instagram-account-no-session-login)
   * [Session Mode 2: With Logged-In Instagram Account (Session Login)](#session-mode-2-with-logged-in-instagram-account-session-login)
   * [Time Zone](#time-zone)
   * [SMTP Settings](#smtp-settings)
   * [Storing Secrets](#storing-secrets)
5. [View Modes](#view-modes)
   * [Traditional Text Mode](#traditional-text-mode)
   * [Terminal Dashboard](#terminal-dashboard-mode)
   * [Web Dashboard](#web-dashboard-mode)
   * [Dashboard View Modes](#dashboard-view-modes)
6. [Usage](#usage)
   * [Docker Usage (Recommended)](#docker-usage-recommended)
      * [Docker Hub Image](#docker-hub-image-recommended)
      * [Build Image Locally](#build-image-locally)
      * [Common Run Scenarios](#common-run-scenarios)
   * [Monitoring Mode](#monitoring-mode)
   * [Email Notifications](#email-notifications)
   * [Webhook Notifications](#webhook-notifications)
   * [Follower Churn Detection](#follower-churn-detection)
   * [Skipping Follow Changes](#skipping-follow-changes)
   * [CSV Export](#csv-export)
   * [Output Directory](#output-directory)
   * [Detection of Changed Profile Pictures](#detection-of-changed-profile-pictures)
   * [Displaying Images in Your Terminal](#displaying-images-in-your-terminal)
   * [Check Intervals](#check-intervals)
   * [Signal Controls (macOS/Linux/Unix)](#signal-controls-macoslinuxunix)
   * [Coloring Log Output with GRC](#coloring-log-output-with-grc)
7. [How to Prevent Getting Challenged and Account Suspension](#how-to-prevent-getting-challenged-and-account-suspension)
8. [Troubleshooting](#troubleshooting)
9. [Change Log](#change-log)
10. [Maintainers](#maintainers)
11. [License](#license)

<a id="requirements"></a>
## Requirements

Choose one runtime path:

* **Python path**:
  * [Python](https://www.python.org/downloads/) 3.9 or higher
  * Libraries: [instaloader](https://github.com/instaloader/instaloader), `requests`, `python-dateutil`, `pytz`, `tzlocal`, `python-dotenv`, `tqdm`, `rich` (for Terminal Dashboard), `flask` (for Web Dashboard)
* **Container path** (Python is not required on host):
  * Any Docker-compatible runtime such as:
    * [Docker Desktop](https://docs.docker.com/get-started/get-docker/) (macOS, Windows, Linux)
    * [Docker Engine](https://docs.docker.com/engine/install/) (Linux)
    * [Colima](https://colima.run/docs/installation/) with Docker CLI (macOS)
    * [OrbStack](https://docs.orbstack.dev/quick-start) (macOS)
    * [Rancher Desktop](https://docs.rancherdesktop.io/getting-started/installation/) with Moby or Docker CLI enabled (macOS, Windows, Linux)

Tested on:

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

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

<a id="installation"></a>
## Installation

<a id="install-from-pypi"></a>
### Install from PyPI

```sh
pip install instagram_monitor
```

<a id="install-from-docker-hub"></a>
### Install from Docker Hub

```sh
docker pull misiektoja/instagram-monitor:latest
```

For run examples and key scenarios see 🐳 [Docker Usage (Recommended)](#docker-usage-recommended).

<a id="manual-installation"></a>
### Manual Installation

Download the *[instagram_monitor.py](https://raw.githubusercontent.com/misiektoja/instagram_monitor/refs/heads/main/instagram_monitor.py)* file to the desired location.

Install dependencies via pip:

```sh
pip install instaloader requests python-dateutil pytz tzlocal python-dotenv tqdm rich flask
```

**Note:** `rich` is required for the Terminal Dashboard, `flask` is required for the Web Dashboard. If Rich or Flask is not installed, the corresponding dashboard is disabled automatically.

Alternatively, from the downloaded *[requirements.txt](https://raw.githubusercontent.com/misiektoja/instagram_monitor/refs/heads/main/requirements.txt)*:

```sh
pip install -r requirements.txt
```

<a id="upgrading"></a>
### Upgrading

To upgrade to the latest version when installed from PyPI:

```sh
pip install instagram_monitor -U
```

If you installed manually, download the newest *[instagram_monitor.py](https://raw.githubusercontent.com/misiektoja/instagram_monitor/refs/heads/main/instagram_monitor.py)* file to replace your existing installation.

If you run from Docker Hub, pull the newer image tag:

```sh
docker pull misiektoja/instagram-monitor:latest
```

If you prefer pinned releases instead of `latest`, pull a specific version tag:

```sh
docker pull misiektoja/instagram-monitor:<version>
```

If you run a locally built image, rebuild it to pick up new changes:

```sh
docker build --pull -t instagram_monitor:local .
```

<a id="quick-start"></a>
## Quick Start

If you prefer to run it in a container, jump to 🐳 [Docker Usage (Recommended)](#docker-usage-recommended).

- Track the `target_insta_user` in [session mode 1](#session-mode-1-without-logged-in-instagram-account-no-session-login) (no session login - anonymous):

```sh
instagram_monitor <target_insta_user>
```

Or if you installed [manually](#manual-installation):

```sh
python3 instagram_monitor.py <target_insta_user>
```

- Track the `target_insta_user` in [session mode 2](#option-3-session-login-using-firefox-cookies-recommended) (with session login via Firefox web browser):

```sh
# log in to the Instagram account (your_insta_user) via Firefox web browser
instagram_monitor --import-firefox-session
instagram_monitor -u <your_insta_user> <target_insta_user>
```

- You can also launch the **[Web Dashboard](#web-dashboard-mode)** along with tracking:

```sh
instagram_monitor <target_insta_user> --web-dashboard
```

To get the list of all supported command-line arguments / flags:

```sh
instagram_monitor --help
```

<a id="configuration"></a>
## Configuration

<a id="configuration-file"></a>
### Configuration File

Most settings can be configured via command-line arguments.

If you want to have it stored persistently, generate a default config template and save it to a file named `instagram_monitor.conf`:

```sh
# On macOS, Linux or Windows Command Prompt (cmd.exe)
instagram_monitor --generate-config > instagram_monitor.conf

# On Windows PowerShell (recommended to avoid encoding issues)
instagram_monitor --generate-config instagram_monitor.conf
```

> **IMPORTANT**: On **Windows PowerShell**, using redirection (`>`) can cause the file to be encoded in UTF-16, which will lead to "null bytes" errors when running the tool. It is highly recommended to provide the filename directly as an argument to `--generate-config` to ensure UTF-8 encoding.

Edit the `instagram_monitor.conf` file and change any desired configuration options (detailed comments are provided for each).

**Note**: Since **v3.0**, you can also change nearly all configuration settings and generate config file via the **[Web Dashboard](#web-dashboard-mode)**.

<a id="session-mode-1-without-logged-in-instagram-account-no-session-login"></a>
### Session Mode 1: Without Logged-In Instagram Account (No Session Login)

In this mode, the tool operates without logging in to an Instagram account (anonymous).

You can still monitor basic user activity such as new or deleted posts (excluding reels and stories due to Instagram API limitations), bio changes and changes in follower/following counts. However, you won't see which specific followers/followings were added or removed.

This mode requires no setup, is easy to use and is resistant to Instagram's anti-bot mechanisms and CAPTCHA challenges.

<a id="session-mode-2-with-logged-in-instagram-account-session-login"></a>
### Session Mode 2: With Logged-In Instagram Account (Session Login)

In this mode, the tool uses an Instagram session login to access additional data. This includes detailed insights into new posts, reels and stories, also about added or removed followers/followings.

**Important**: It is highly recommended to use a dedicated Instagram account when using this tool in session login mode. While the risk of account suspension is generally low (in practice, accounts often stay active long-term), Instagram may still flag it as an automated tool. This can lead to challenges presented by Instagram that must be dismissed manually. To minimize any chance of detection, make sure to follow the best practices outlined [here](#how-to-prevent-getting-challenged-and-account-suspension).

<a id="option-1-basic-session-login-not-recommended"></a>
#### Option 1: Basic Session Login (not recommended)

You can provide your Instagram username (`your_insta_user`) and password directly in the `instagram_monitor.conf` configuration file, [environment variable](#storing-secrets) or via the `-u` and `-p` flags.

However, this triggers a full login every time the tool runs, increasing the chance of detection and account lockouts.

If you store the `SESSION_PASSWORD` in a dotenv file you can update its value and send a `SIGHUP` signal to the process to reload the file with the new password without restarting the tool. More info in [Storing Secrets](#storing-secrets) and [Signal Controls (macOS/Linux/Unix)](#signal-controls-macoslinuxunix).

<a id="option-2-session-login-via-instaloader-better-but-can-be-detected"></a>
#### Option 2: Session Login via Instaloader (better, but can be detected)

A better approach is to use `Instaloader` to perform a one-time login and save the session:

```sh
instaloader -l <your_insta_user>
```

This saves the session locally. However, frequent follower/following/stories changes can still lead to detection, as Instagram may flag this as automated behavior.

<a id="option-3-session-login-using-firefox-cookies-recommended"></a>
#### Option 3: Session Login Using Firefox Cookies (recommended)

The most reliable method is to reuse an existing Instagram session from your Firefox web browser, along with manually specifying the user agent.

Log in to your account (`your_insta_user`) in Firefox, then run:

```sh
instagram_monitor --import-firefox-session
```

Since **v3.0**, you can also perform this import easily via the **[Web Dashboard](#web-dashboard-mode)** (no command line required). Simply open the dashboard, go to the **Session** page and click **Detect Firefox Profiles**.

The tool will detect available Firefox profiles with a `cookies.sqlite` file. If multiple profiles are found, it will prompt you to select one, then import the session and save it via Instaloader.

To use a specific Firefox profile path:

```sh
instagram_monitor --import-firefox-session --cookie-file "/path/cookies.sqlite"
```

You can adjust the default Firefox cookie directory permanently via `FIREFOX_*_COOKIE` configuration options.

The session login method using Firefox cookies has the added benefit of blending tool activity with regular user behavior. Interacting with Instagram via Firefox every few days (scrolling, liking posts etc.) helps maintain session trust. However, avoid overlapping browser activity with tool activity, as simultaneous actions can trigger suspicious behavior flags.

<a id="user-agent"></a>
##### User Agent

It is also recommended to use the exact user agent string from your Firefox web browser:
- open Firefox and type `about:support` in the address bar
- find the `User Agent` value under the `Application Basics` section and copy it
- set this value via the `USER_AGENT` configuration option or by using the `--user-agent` flag (since **v3.0**, you can also do it easily via the **[Web Dashboard](#web-dashboard-mode)**)

<a id="time-zone"></a>
### Time Zone

By default, time zone is auto-detected using `tzlocal`. You can set it manually in `instagram_monitor.conf`:

```ini
LOCAL_TIMEZONE='Europe/Warsaw'
```

You can get the list of all time zones supported by pytz like this:

```sh
python3 -c "import pytz; print('\n'.join(pytz.all_timezones))"
```

Since **v3.0** you can also change from the default 24-hour time format to a 12-hour format via the `TIME_FORMAT_12H` config option.

<a id="smtp-settings"></a>
### SMTP Settings

If you want to use email notifications functionality, configure SMTP settings in the `instagram_monitor.conf` file.

Verify your SMTP settings by using `--send-test-email` flag (the tool will try to send a test email notification):

```sh
instagram_monitor --send-test-email
```

<a id="storing-secrets"></a>
### Storing Secrets

It is recommended to store secrets like `SESSION_PASSWORD`, `SMTP_PASSWORD` or `WEBHOOK_URL` as either an environment variable or in a dotenv file.

Set the needed environment variables using `export` on **Linux/Unix/macOS/WSL** systems:

```sh
export SESSION_PASSWORD="your_instagram_session_password"
export SMTP_PASSWORD="your_smtp_password"
export WEBHOOK_URL="https://discord.com/api/webhooks/..."
```

On **Windows Command Prompt** use `set` instead of `export` and on **Windows PowerShell** use `$env`.

Alternatively store them persistently in a dotenv file (recommended):

```ini
SESSION_PASSWORD="your_instagram_session_password"
SMTP_PASSWORD="your_smtp_password"
WEBHOOK_URL="https://discord.com/api/webhooks/..."
```

By default the tool will auto-search for dotenv file named `.env` in current directory and then upward from it.

You can specify a custom file with `DOTENV_FILE` or `--env-file` flag:

```sh
instagram_monitor <target_insta_user> --env-file /path/.env-instagram_monitor
```

 You can also disable `.env` auto-search with `DOTENV_FILE = "none"` or `--env-file none`:

```sh
instagram_monitor <target_insta_user> --env-file none
```

As a fallback, you can also store secrets in the configuration file or source code.


<a id="view-modes"></a>
## View Modes

The tool provides three distinct ways to visualize monitoring activity:

1. **Traditional Text Mode**: Standard CLI output, best for logging and background processes.
2. **Terminal Dashboard**: A rich, interactive terminal interface with real-time stats.
3. **Web Dashboard**: A modern web interface accessible via your browser.

---

<a id="traditional-text-mode"></a>
### Traditional Text Mode

This is the classic command-line output. It is characterized by:
- **Clean, sequential logging**: Every event is printed as it happens with a timestamp.
- **Persistence**: Ideal for running in the background (e.g., via `nohup` or `tmux`) where you want a full history of events in your terminal scrollback or log files.
- **Low Overhead**: Minimal resource usage and compatible with any terminal.

It is the default mode of operation.

---

<a id="terminal-dashboard-mode"></a>
### Terminal Dashboard

The Terminal Dashboard provides a beautiful, live-updating interface directly in your terminal. It requires the `rich` library.

To enable the terminal dashboard, use the `--dashboard` flag (or set `DASHBOARD_ENABLED = True` in your config).

**Key Features:**
- **Visual Analytics**: Real-time display of tracked targets with number of followers, followings, posts, visibility and story status.
- **Live Activity Log**: A scrolling view of the last few events.
- **Interactive Toggles**: Press **'m'** to switch between 'User' and 'Config' views instantly.
- **Remote Control**: Start, stop or recheck monitoring for all targets directly from the terminal.
- **Uptime & Status**: Clean header showing tool version, status and total runtime.

**Keyboard Shortcuts:**
- **'m'**: Toggle dashboard view (User/Config)
- **'s'**: **Start All** monitoring
- **'x'**: **Stop All** monitoring
- **'r'**: **Recheck All** targets
- **'q'**: **Exit** the tool
- **'h'**: Show help (lists commands in the activity log)

```sh
instagram_monitor target1 target2 --dashboard
```

<p align="center">
   <img src="https://raw.githubusercontent.com/misiektoja/instagram_monitor/refs/heads/main/assets/instagram_monitor_terminal_dashboard.png" alt="instagram_monitor_terminal_dashboard_screenshot" width="100%"/>
</p>

---

<a id="web-dashboard-mode"></a>
### Web Dashboard

A modern, real-time web interface running on your local machine (default: `http://127.0.0.1:8000/`).

**Key Features:**
- **Full Control Panel**: Add or remove monitoring targets directly from the browser.
- **Visual Analytics**: Real-time display of tracked targets with number of followers, followings, posts, visibility and story status.
- **Live Activity Log**: A scrolling view of the last few events.
- **Manual Trigger**: A "Recheck" button to force an immediate update for specific or all users.
- **Remote Management**: Start or stop monitoring for specific or all targets with a single click.
- **Synchronization**: Changes made in the web dashboard (like mode toggles) are reflected in the terminal instantly.
- **Dynamic Configuration**: Configure sessions and settings without touching the terminal or config files.

To enable the web dashboard, use the `--web-dashboard` flag (or set `WEB_DASHBOARD_ENABLED = True` in your config).

**Flexible Usage:**
- **Standard Monitoring**: Provide targets on the CLI and the dashboard acts as a live mirror and remote management interface.
- **Control Panel Mode**: Start the tool with **only** the `--web-dashboard` flag (no initial targets). The script will wait for you to add users through the browser.

```sh
# Starting with initial targets
instagram_monitor target1 target2 --web-dashboard

# Starting as a pure control panel
instagram_monitor --web-dashboard
```

The web dashboard requires `flask`. If flask is missing, it will be disabled while the console output remains active.

<p align="center">
   <img src="https://raw.githubusercontent.com/misiektoja/instagram_monitor/refs/heads/main/assets/instagram_monitor_web_dashboard.png" alt="instagram_monitor_web_dashboard_screenshot" width="90%"/>
</p>

<p align="center">
   <img src="https://raw.githubusercontent.com/misiektoja/instagram_monitor/refs/heads/main/assets/instagram_monitor_web_dashboard_settings.png" alt="instagram_monitor_web_dashboard_settings_screenshot" width="90%"/>
</p>

---

<a id="dashboard-view-modes"></a>
### Dashboard View Modes

Both the Terminal and Web dashboards support two levels of information density:

1. **User Mode** (`user`):
   - Simple, minimal interface.
   - Focuses on core stats and latest activity.
   - Ideal for "always-on" monitoring.

2. **Config Mode** (`config`):
   - Detailed view showing all internal settings.
   - Displays User Agent strings, Hour Ranges, Jitter status and more.
   - Useful for auditing your setup and verifying configuration.

Toggle seamlessly between modes using the **'m'** key or the web dashboard toggle button.

<a id="usage"></a>
## Usage

<a id="docker-usage-recommended"></a>
### Docker Usage (Recommended)

Running via [Docker](https://www.docker.com) is the easiest setup for most users and avoids local Python dependency management.

<a id="docker-hub-image-recommended"></a>
#### Docker Hub Image

A prebuilt multi-architecture image is available on Docker Hub: [`misiektoja/instagram-monitor`](https://hub.docker.com/r/misiektoja/instagram-monitor)

Run and show help:

```sh
docker run --rm -it misiektoja/instagram-monitor --help
```

<a id="build-image-locally"></a>
#### Build Image Locally

If you want to build from source:

```sh
docker build -t instagram_monitor:local .
docker run --rm -it instagram_monitor:local --help
```

If you prefer the local image, replace `misiektoja/instagram-monitor` with `instagram_monitor:local` in the Docker commands below.

<a id="common-run-scenarios"></a>
#### Common Run Scenarios

**Shell note:** The examples below use Bash/Zsh variables (`$PWD`, `$HOME`). In PowerShell use `${PWD}` and `${HOME}` or replace them with absolute paths in `-v` mounts.

1. Basic monitoring with persistent data and session storage:

```sh
docker run --rm -it --init -v "$PWD:/data" -v instagram_monitor_session:/home/instagram/.config/instaloader misiektoja/instagram-monitor <target_insta_user>
```

This keeps generated files in your current directory and keeps Instaloader sessions in the Docker volume `instagram_monitor_session`.

2. Use config file and dotenv from your current directory:

```sh
docker run --rm -it --init -v "$PWD:/data" -v instagram_monitor_session:/home/instagram/.config/instaloader misiektoja/instagram-monitor <target_insta_user> --config-file /data/instagram_monitor.conf --env-file /data/.env
```

3. Run Web Dashboard and access it from host browser:

Set `WEB_DASHBOARD_HOST = "0.0.0.0"` in `instagram_monitor.conf`, then run:

```sh
docker run --rm -it --init -v "$PWD:/data" -v instagram_monitor_session:/home/instagram/.config/instaloader -p 8000:8000 misiektoja/instagram-monitor <target_insta_user> --web-dashboard
```

Open [http://127.0.0.1:8000/](http://127.0.0.1:8000/) on your host.

4. Import Firefox session cookies on Linux host:

```sh
docker run --rm -it --init -v "$PWD:/data" -v instagram_monitor_session:/home/instagram/.config/instaloader -v "$HOME/.mozilla/firefox:/home/instagram/.mozilla/firefox:ro" misiektoja/instagram-monitor --import-firefox-session
```

5. Import Firefox session cookies on macOS host from explicit cookie file:

```sh
docker run --rm -it --init -v "$PWD:/data" -v instagram_monitor_session:/home/instagram/.config/instaloader -v "$HOME/Library/Application Support/Firefox/Profiles/<profile>/cookies.sqlite:/cookies/cookies.sqlite:ro" misiektoja/instagram-monitor --import-firefox-session --cookie-file /cookies/cookies.sqlite
```

Once imported, run with `-u <your_insta_user>` as usual and the session file from the persistent volume will be reused.

<a id="monitoring-mode"></a>
### Monitoring Mode

To monitor specific user activity in [session mode 1](#session-mode-1-without-logged-in-instagram-account-no-session-login) (no session login - anonymous), just type Instagram username as a command-line argument (`target_insta_user` in the example below):

```sh
instagram_monitor <target_insta_user>
```

To monitor specific user activity in [session mode 2](#session-mode-2-with-logged-in-instagram-account-session-login) (with session login), you also need to specify your Instagram account name (`your_insta_user` in the example below) via `SESSION_USERNAME` configuration option or `-u` flag:

```sh
instagram_monitor -u <your_insta_user> <target_insta_user>
```

Since **v3.0** you can also launch the **[Web Dashboard](#web-dashboard-mode)** along with tracking:

```sh
instagram_monitor -u <your_insta_user> <target_insta_user> --web-dashboard
```

By default, the tool looks for a configuration file named `instagram_monitor.conf` in:
 - current directory
 - home directory (`~`)
 - script directory

 If you generated a configuration file as described in [Configuration](#configuration), but saved it under a different name or in a different directory, you can specify its location using the `--config-file` flag:

```sh
instagram_monitor <target_insta_user> --config-file /path/instagram_monitor_new.conf
```

The tool runs until interrupted (`Ctrl+C`). Use `tmux` or `screen` for persistence.

You can monitor multiple Instagram users in **one process** by passing multiple target usernames:

```sh
instagram_monitor target_user_1 target_user_2 target_user_3
```

**Note**: You can also add and remove monitoring targets directly via the **[Web Dashboard](#web-dashboard-mode)** without restarting the tool.

To reduce the chance of triggering Instagram anti-bot mechanisms, the tool will **stagger** the start of each target's monitoring loop (auto-spread across your `INSTA_CHECK_INTERVAL` by default). You can override it with:

```sh
instagram_monitor target_user_1 target_user_2 --targets-stagger 300
```

The tool automatically saves its output to an `instagram_monitor_<suffix>.log` file. It can be changed in the settings via `INSTA_LOGFILE` configuration option or disabled completely via `DISABLE_LOGGING` / `-d` flag.

- In single-target mode, `<suffix>` is the username.
- In multi-target mode, `<suffix>` is the sorted list of target usernames joined with underscores.

The tool in mode 2 (session login) also saves the list of followings & followers to these files:
- `instagram_<username>_followings.json`
- `instagram_<username>_followers.json`

Thanks to this we do not need to re-fetch it every time the tool is restarted and we can also detect changes since the last usage of the tool.

When downloading lists of followers or followings, a **progress bar** is displayed showing real-time download progress, including statistics such as names per request, total requests, elapsed time and estimated remaining time. Progress updates are shown in the terminal only (to avoid cluttering log files), with the final completion state written to the log file for reference.

The tool also saves the user profile picture to `instagram_<username>_profile_pic*.jpg` files.

It also saves downloaded posts/reels images & videos to:
- `instagram_<username>_post/reel_YYYYmmdd_HHMMSS.jpg`
- `instagram_<username>_post/reel_YYYYmmdd_HHMMSS.mp4`

And downloaded stories images & videos to:
- `instagram_<username>_story_YYYYmmdd_HHMMSS.jpg`
- `instagram_<username>_story_YYYYmmdd_HHMMSS.mp4`


<a id="email-notifications"></a>
### Email Notifications

To enable email notifications for various events (such as new posts, reels and stories, changes in followings, bio updates, changes in profile picture and visibility):
- set `STATUS_NOTIFICATION` to `True`
- or use the `-s` flag
- or toggle it via the **Settings** menu in the **Web Dashboard**

```sh
instagram_monitor <target_insta_user> -s
```

To also get email notifications about changed followers:
- set `FOLLOWERS_NOTIFICATION` to `True`
- or use the `-m` flag
- or toggle it via the **Settings** menu in the **Web Dashboard**

```sh
instagram_monitor <target_insta_user> -m
```

To disable sending an email on errors (enabled by default):
- set `ERROR_NOTIFICATION` to `False`
- or use the `-e` flag
- or toggle it via the **Settings** menu in the **Web Dashboard**

```sh
instagram_monitor <target_insta_user> -e
```

Make sure you defined your SMTP settings earlier (see [SMTP settings](#smtp-settings)).

Example email:

<p align="center">
   <img src="https://raw.githubusercontent.com/misiektoja/instagram_monitor/refs/heads/main/assets/instagram_monitor_email_notifications.png" alt="instagram_monitor_email_notifications" width="80%"/>
</p>

<a id="webhook-notifications"></a>
### Webhook Notifications

The tool supports webhook notifications (compatible with **Discord** and other webhook services) for all monitored events (posts, reels, stories, followings, followers, bio, profile visibility, profile picture changes and errors).

<p align="center">
   <img src="https://raw.githubusercontent.com/misiektoja/instagram_monitor/refs/heads/main/assets/instagram_monitor_discord.png" alt="instagram_monitor_discord_screenshot" width="80%"/>
</p>

#### 1. Configure Discord Webhook
If you are new to Discord, follow these steps to get your **Webhook URL**:

1.  **Create a Server**: Click the **+** (Plus) icon on the left sidebar ("Add a Server") -> **Create My Own** -> **For me and my friends**.
2.  **Create/Edit a Channel**: In your new server, find the **#general** channel (or create a new one). Click the **Edit Channel** icon (⚙️ gear) next to the channel name.
3.  **Create Webhook**: Go to **Integrations** in the left menu -> **Webhooks** -> **New Webhook**.
4.  **Copy URL**: Click on the new webhook (often named "Spidey Bot", you can rename it) and click **Copy Webhook URL**.

#### 2. Enable in the Tool
- set `WEBHOOK_ENABLED` to `True` and `WEBHOOK_URL` to your copied URL in `instagram_monitor.conf`
- or use an [environment variable](#storing-secrets) or a dotenv file for `WEBHOOK_URL`
- or use the `--webhook-url` flag (alternatively use the `--webhook` flag if URL is already in config)
- or toggle it via the **Settings** menu in the **Web Dashboard**

```sh
# Enable with URL
instagram_monitor <target_insta_user> --webhook-url "https://discord.com/api/webhooks/..."

# Explicitly enable/disable if URL is in config
instagram_monitor <target_insta_user> --webhook
instagram_monitor <target_insta_user> --no-webhook
```

#### 3. Test your settings
You can verify your configuration by sending a test notification:

```sh
# Verify settings from configuration file
instagram_monitor --send-test-webhook

# Verify a specific URL from command line
instagram_monitor --webhook-url "https://discord.com/api/webhooks/..." --send-test-webhook
```

#### 4. Advanced Configuration
By default, all webhook notification types (status, followers, errors) are **disabled**. You must explicitly enable what you want the tool to send:

- Use `--webhook-status` to toggle status notifications (new posts, reels, stories, bio, visibility, profile pic)
- Use `--webhook-followers` to toggle follower/following change notifications
- Use `--webhook-errors` to toggle error notifications

Example with explicit control:
```sh
# Enable webhooks and specifically choose what to send
instagram_monitor <target_insta_user> --webhook-url "..." --webhook-status --webhook-followers --webhook-errors
```

Configuration file options (all disabled by default):
```ini
WEBHOOK_ENABLED = False
WEBHOOK_URL = "https://discord.com/api/webhooks/..."
WEBHOOK_USERNAME = "Instagram Monitor"
WEBHOOK_AVATAR_URL = ""
WEBHOOK_STATUS_NOTIFICATION = False
WEBHOOK_FOLLOWERS_NOTIFICATION = False
WEBHOOK_ERROR_NOTIFICATION = False
```

<a id="follower-churn-detection"></a>
### Follower Churn Detection

When enabled, the tool fetches the full list of followers and followings on **every check** (not just when counts change) and compares usernames to detect changes. This is useful for scenarios where:

- Someone unfollows and someone else follows at the same time (count stays the same)
- You want to track exactly who followed/unfollowed even without count changes
- You need comprehensive monitoring of all follower/following activity

To enable follower churn detection:
- set `FOLLOWERS_CHURN_DETECTION` to `True`
- or use the `--followers-churn` flag
- or toggle it via the **Settings** menu in the **Web Dashboard**

**Note**: This feature is automatically disabled if `SKIP_FOLLOW_CHANGES` is active, as detailed tracking is not possible when follow-related reporting is suppressed. It also requires [Session Mode 2](#session-mode-2-with-logged-in-instagram-account-session-login).

```sh
instagram_monitor <target_insta_user> --followers-churn
```

**Note**: This feature requires [Session Mode 2](#session-mode-2-with-logged-in-instagram-account-session-login) (session login) to access the Instagram API and it will increase API calls since it fetches the full follower/following lists every check interval, so the risk of account suspension is higher.

<a id="skipping-follow-changes"></a>
### Skipping Follow Changes

If you want to track followers/followings counts in the dashboards, but don't want to get any notifications or logs when they change, you can enable the "Skip Follow Changes" mode.

When enabled:
- **Notifications**: Email and Webhook alerts for follower/following changes are suppressed.
- **Reporting**: Console prints and activity logs for these changes are disabled.
- **CSV Export**: No "Followers Count" or "Followings Count" entries are written to the CSV file.
- **Performance**: High-overhead downloading of full lists is skipped, saving bandwidth and reducing API call volume.

To enable skipping follow changes:
- set `SKIP_FOLLOW_CHANGES` to `True` in your config
- or use the `--skip-follow-changes` flag
- or toggle it via the **Settings** menu in the **Web Dashboard**

```sh
instagram_monitor <target_insta_user> --skip-follow-changes
```

<a id="csv-export"></a>
### CSV Export

If you want to save all Instagram user's activities and profile changes to a CSV file, set `CSV_FILE` or use `-b` flag:

```sh
instagram_monitor <target_insta_user> -b instagram_username.csv
```

The file will be automatically created if it does not exist.

The tool uses the following logic for CSV path resolution:

1.  **Absolute Path**:
    *   **Single-target mode**: The file is saved exactly where specified.
    *   **Multi-target mode**: The absolute path is used as a base; separate files are created for each user (e.g., `/path/file_user1.csv`). Isolation is preserved.
2.  **Relative Path + `OUTPUT_DIR`**: If you provide a relative path and have `OUTPUT_DIR` configured, the file is saved in the `csvs/` subdirectory:
    *   **Single-target mode**: `OUTPUT_DIR/csvs/<filename>` (uses basename of your input)
    *   **Multi-target mode**: `OUTPUT_DIR/<username>/csvs/<filename>` (uses basename of your input)
3.  **Relative Path + no `OUTPUT_DIR`**:
    *   **Single-target mode**: Saved as specified in the current working directory.
    *   **Multi-target mode**: One file per user is created in the current working directory using a suffix: `<CSV_FILE_basename>_<username>.csv`.

<a id="output-directory"></a>
### Output Directory

By default, the tool saves all generated files (JSON, images, videos, logs) in the current working directory.

You can specify a custom root directory for all output files using the `-o` / `--output-dir` flag or `OUTPUT_DIR` configuration option:

```sh
instagram_monitor <target_insta_user> -o /path/to/downloads
```

The tool will organize files into subdirectories:

- **Output structure**: The layout depends on whether you monitor one or multiple users:

  - **Single-target mode**: All files are organized into subdirectories directly under `OUTPUT_DIR`:
    - `OUTPUT_DIR/images/`
    - `OUTPUT_DIR/videos/`
    - `OUTPUT_DIR/json/`
    - `OUTPUT_DIR/logs/`
    - `OUTPUT_DIR/csvs/`

  - **Multi-target mode**: Each user gets their own isolated subdirectory:
    - `OUTPUT_DIR/<username>/images/`
    - `OUTPUT_DIR/<username>/videos/`
    - `OUTPUT_DIR/<username>/json/`
    - `OUTPUT_DIR/<username>/logs/`
    - `OUTPUT_DIR/<username>/csvs/`

Common messages (like the summary screen or global errors) are automatically broadcasted to all active log files.

This helps keep your files organized, especially when monitoring multiple users.

<a id="detection-of-changed-profile-pictures"></a>
### Detection of Changed Profile Pictures

The tool can detect when a monitored user changes their profile picture. Notifications appear in the console and (if the `-s` flag is enabled) via email.

This feature is enabled by default. To disable it, either:

- set the `DETECT_CHANGED_PROFILE_PIC` to `False`
- or use the `-k` flag
- or toggle it via the **Settings** menu in the **Web Dashboard**

<a id="how-it-works"></a>
#### How It Works

Since Instagram periodically changes the profile picture URL even when the image is the same, the tool performs a binary comparison of JPEG files to detect actual changes.

On the first run, it saves the current profile picture to `instagram_<username>_profile_pic.jpg`

On each subsequent check a new image is fetched and it is compared byte-for-byte with the saved image.

If a change is detected, the old picture is moved to `instagram_<username>_profile_pic_old.jpg` and the new one is saved to:
- `instagram_<username>_profile_pic.jpg` (current)
- `instagram_<username>_profile_pic_YYmmdd_HHMM.jpg` (for history)

<a id="empty-profile-picture-detection"></a>
#### Empty Profile Picture Detection

The tool also has built-in detection of empty profile pictures. Instagram does not indicate an empty user's profile image in their API; that's why the tool detects it by using an empty profile image template (which appears to be identical on a binary level for all users).

To enable this:
- download the [instagram_profile_pic_empty.jpg](https://raw.githubusercontent.com/misiektoja/instagram_monitor/main/instagram_profile_pic_empty.jpg) file
- place it in the directory where you run the tool. **Note**: If installed via `pip`, this file is already bundled; however, any local file in your working directory will take **priority** over the bundled default.

Without this file, the tool will treat an empty profile picture as a regular image. For example, if a user removes their profile picture, it would be treated as a change rather than a removal.

<a id="displaying-images-in-your-terminal"></a>
### Displaying Images in Your Terminal

If you have `imgcat` installed, you can use the feature of displaying profile pictures and stories/reels/posts images right in your terminal.

To do this, set the path to your `imgcat` binary in the `IMGCAT_PATH` configuration option.

If you specify only the binary name, it will be auto-searched in your PATH.

Set it to empty to disable this feature.

<a id="check-intervals"></a>
### Check Intervals

If you want to customize polling interval, use `-c` flag (or `INSTA_CHECK_INTERVAL` configuration option):

```sh
instagram_monitor <target_insta_user> -c 3600
```

**Note**: You can also adjust check intervals and randomization timers live via the **Settings** menu in the **Web Dashboard**.

It is generally not recommended to use values lower than 1 hour as it will be quickly picked up by Instagram automated tool detection mechanisms.

In order to make the tool's behavior less suspicious for Instagram, by default the polling interval is randomly picked from the range:

```
[ INSTA_CHECK_INTERVAL (-c) - RANDOM_SLEEP_DIFF_LOW (-i) ]
                         ⇄
[ INSTA_CHECK_INTERVAL (-c) + RANDOM_SLEEP_DIFF_HIGH (-j) ]
```

This means each check will happen after a random delay centered around `INSTA_CHECK_INTERVAL` with some variation defined by `RANDOM_SLEEP_DIFF_LOW` and `RANDOM_SLEEP_DIFF_HIGH`.

So having the check interval set to 1 hour (-c 3600), `RANDOM_SLEEP_DIFF_LOW` set to default 15 mins (-i 900) and `RANDOM_SLEEP_DIFF_HIGH` set to default 3 mins (-j 180) means that the check interval will be with every iteration picked from the range of 45 mins to 1 hour and 3 mins.

That's why the check interval information is printed in the console and email notifications as it is essentially a random number.

On top of that you can also define that fetching updates should be done only in specific hour ranges by setting `CHECK_POSTS_IN_HOURS_RANGE` to `True` and then defining proper values for `MIN/MAX_H1/H2` configuration options (see [Use Hour-Range Checking](#use-hour-range-checking) for more information).

<a id="signal-controls-macoslinuxunix"></a>
### Signal Controls (macOS/Linux/Unix)

The tool has several signal handlers implemented which allow to change behavior of the tool without a need to restart it with new configuration options / flags.

List of supported signals:

| Signal | Description |
| ----------- | ----------- |
| USR1 | Toggle email notifications for new posts, reels & stories, changed followings, bio, profile picture, visibility (-s) |
| USR2 | Toggle email notifications for new followers (-m) |
| TRAP | Increase the user activity check interval (by 5 mins) |
| ABRT | Decrease the user activity check interval (by 5 mins) |
| HUP | Reload secrets from .env file |

Send signals with `kill` or `pkill`, e.g.:

```sh
pkill -USR1 -f "instagram_monitor <target_insta_user>"
```

As Windows supports limited number of signals, this functionality is available only on Linux/Unix/macOS.

<a id="coloring-log-output-with-grc"></a>
### Coloring Log Output with GRC

The tool has native **color output** support for terminal since v3.0 (see `COLORED_OUTPUT` and `COLOR_THEME` config options), but you can also use [GRC](https://github.com/garabik/grc) to color logs.

Add to your GRC config (`~/.grc/grc.conf`):

```
# monitoring log file
.*_monitor.*\.log
conf.monitor_logs
```

Now copy the [conf.monitor_logs](https://raw.githubusercontent.com/misiektoja/instagram_monitor/refs/heads/main/grc/conf.monitor_logs) to your `~/.grc/` and log files should be nicely colored when using `grc` tool.

Example:

```sh
grc tail -F -n 100 instagram_monitor_<username>.log
```

<a id="how-to-prevent-getting-challenged-and-account-suspension"></a>
## How to Prevent Getting Challenged and Account Suspension

As mentioned earlier it is highly recommended to use a dedicated Instagram account when using this tool in session login mode. While the risk of account suspension is generally low (in practice, accounts often stay active long-term), Instagram may still flag it as an automated tool. This can lead to challenges presented by Instagram that must be dismissed manually.

To minimize any chance of detection, make sure to follow the best practices outlined below.

<a id="sign-in-using-session-mode-with-firefox-cookies"></a>
### Sign In Using Session Mode with Firefox Cookies

Use your Firefox web browser to log in, ensuring the session looks natural and consistent to Instagram. Follow instructions described [here](#option-3-session-login-using-firefox-cookies-recommended)

<a id="set-the-correct-user-agent"></a>
### Set the Correct User-Agent

Always pass the exact web browser user agent string from your Firefox web browser by using `USER_AGENT` configuration option or the `--user-agent` flag. This helps maintain device consistency during automated actions. Follow instructions described [here](#user-agent)

<a id="use-the-human-mode"></a>
### Use the Human Mode

Since v1.7, the tool includes a new experimental **Be Human** mode that makes it behave more like a real user to reduce bot detection.

It is disabled by default, but you can enable it via `BE_HUMAN` configuration option, `--be-human` flag or by toggling it via the **Settings** menu in the **Web Dashboard**.

It is used only with session login (session mode 2).

After each check cycle, the tool will randomly do one or more of these harmless actions:
- View your explore feed: pulls a single post from Instagram's explore feed
- Open your own profile, as if tapping your avatar
- Browse a hashtag: fetches one post from a random tag listed in `MY_HASHTAGS` configuration option
- Look at a profile of someone you follow

By default it does around 5 of these actions spread over 24 hours, but you can adjust it via `DAILY_HUMAN_HITS` option.

If you are interested in your human actions set `BE_HUMAN_VERBOSE` option to `True`.

<a id="use-the-jitter-mode"></a>
### Use the Jitter Mode

Since v1.7, the tool allows to force every HTTP call made by Instaloader to go through a built-in jitter/back-off layer to look more human.

This adds random delay (0.8-3 s) before each request and automatically retries on Instagram's 429 "too many requests" or checkpoint challenges, with exponential back-off (60 s → 120 s → 240 s) and a little extra jitter.

This significantly reduces detection risk, but also makes the tool slower.

You can enable this feature via `ENABLE_JITTER` configuration option or `--enable-jitter` flag.

If you want to see verbose output for HTTP jitter/back-off wrappers set `JITTER_VERBOSE` option to `True`.

<a id="keep-the-polling-interval-reasonable"></a>
### Keep the Polling Interval Reasonable

Avoid setting the polling interval (`INSTA_CHECK_INTERVAL` option or `-c` flag) too aggressively. Use a minimum of 1 hour - longer is better. For example, I set it to 12 hours on test accounts, resulting in only 2 checks per day.

Also consider to randomize the check interval, as explained [here](#check-intervals).

**Important**: When monitoring multiple users in a single process, the effective request rate is multiplied by the number of targets. For example, monitoring 5 users with a 1-hour interval means 5 requests per hour. To maintain the same per-account request rate, increase the check interval proportionally. If you normally use 1 hour for a single user, consider using 5 hours (or more) when monitoring 5 users. The tool automatically staggers requests between targets, but the overall request frequency should still be adjusted based on the total number of monitored users.

<a id="use-hour-range-checking"></a>
### Use Hour-Range Checking

The tool supports limiting fetching updates to specific hours of the day, which helps reduce detection by avoiding requests during times when automated activity might be more suspicious.

When hour-range checking is enabled, the tool will only fetch updates (posts, reels, stories, profile changes, followers/followings) during the configured time windows. Outside these hours, the tool will skip fetching updates but will continue running and wait for the next allowed time window.

To enable this feature, set `CHECK_POSTS_IN_HOURS_RANGE` to `True` and configure the allowed hour ranges using:
- `MIN_H1` and `MAX_H1` - first range of hours (default: 0-4, i.e., midnight to 4:59 AM)
- `MIN_H2` and `MAX_H2` - second range of hours (default: 11-23, i.e., 11:00 AM to 11:59 PM / 23:59)

You can define up to two non-overlapping or overlapping ranges. To disable any range, set both MIN and MAX to 0.

**Note**: You can also enable this feature and configure the allowed hour ranges live via the **Settings** menu in the **Web Dashboard**.

For example, to only allow checks during business hours (9 AM to 5 PM / 17:00), you could set:
- `MIN_H1 = 9`
- `MAX_H1 = 17`
- `MIN_H2 = 0`
- `MAX_H2 = 0`

Hours are specified in 24-hour format (0-23) and are evaluated in your configured time zone (see [Time Zone](#time-zone)).

If you want to see verbose output about when updates are being fetched or skipped, set `HOURS_VERBOSE` to `True`. This is useful for debugging and understanding when the tool is active.

This feature works particularly well when combined with reasonable polling intervals, as it ensures that even if your check interval triggers, requests will only be made during the configured time windows, making your activity pattern look more natural.

<a id="do-not-monitor-too-many-users"></a>
### Do Not Monitor Too Many Users

It is recommended to limit the number of users monitored by a single account, especially if they post frequent updates. When using multi-user monitoring (monitoring multiple users in one process), keep in mind that the total request volume increases with each additional target. In some cases, it may be best to create a separate account for additional users and even run it from a different IP address to reduce the risk of detection.

<a id="use-only-needed-functionality"></a>
### Use Only Needed Functionality

Frequent updates to certain data types, such as new stories or posts/reels, are more likely to flag the account as an automated tool compared to profile changes or lists of followers/followings.

If certain data isn't essential for your use case, consider disabling its retrieval. The tool provides fine-grained control, for example you can skip fetching stories details (`-r`), posts/reels details (`-w`), the list of followings (`-g` flag) and followers (`-f`).

**Note**: All of these fine-grained tracking options can also be toggled live via the **Settings** menu in the **Web Dashboard**.

<a id="use-two-factor-authentication-2fa"></a>
### Use Two-Factor Authentication (2FA)

Activate 2FA on the account used for monitoring. It adds credibility to your account and reduces the likelihood of security flags.

<a id="avoid-using-vpns"></a>
### Avoid Using VPNs

Refrain from logging in via VPNs, especially with IPs in different regions. Sudden location changes can trigger Instagram's security systems.

<a id="use-the-account-for-normal-activities"></a>
### Use the Account for Normal Activities

If you have created a new account for monitoring and you are using [Session Login Using Firefox](#option-3-session-login-using-firefox-cookies-recommended), make sure to behave like a regular user for several days. New accounts are more closely monitored by Instagram's bot detection systems. Watch content, post stories or reels and leave comments - this helps establish a natural activity pattern.

Once you start using the tool, try to blend its actions with normal usage. However, avoid overlapping browser activity with tool activity, as simultaneous actions can trigger suspicious behavior flags.

<a id="troubleshooting"></a>
## Troubleshooting

In case of issues, run the tool with the `--debug` flag. It shows full HTTP traffic and internal script logic. Create a new issue in Github if you cannot fix it yourself.

### Choosing the Right Logging Level

- **Default Mode**: Silent and clean. Only logs changes (new posts, bio updates, etc.) and critical errors. Best for long-term production use.
- **Verbose Mode (`--verbose`)**: Recommended for most users. Shows when the next check is scheduled and confirms that the loop is running correctly.
- **Debug Mode (`--debug`)**: For developers or fixing issues. Shows full HTTP traffic, internal script logic

**Note**: Both **Verbose** and **Debug** modes can be toggled live via the **Settings** menu in the **Web Dashboard**.

<a id="change-log"></a>
## Change Log

See [RELEASE_NOTES.md](https://github.com/misiektoja/instagram_monitor/blob/main/RELEASE_NOTES.md) for details.

<a id="maintainers"></a>
## Maintainers

- 👤 **misiektoja** ([@misiektoja](https://github.com/misiektoja))
- 👤 **tomballgithub** ([@tomballgithub](https://github.com/tomballgithub))

<a id="license"></a>
## License

Licensed under GPLv3. See [LICENSE](https://github.com/misiektoja/instagram_monitor/blob/main/LICENSE).
