Configuration¶
Examples on this page use the PyPI command instagram_monitor. If you chose another installation, replace that command with the matching command prefix. Keep all options after the prefix. A container can see host files only through its mounts, so paths to files in the current directory must start with /data.
Configuration File¶
You can pass most settings as command-line options or save them in a configuration file for later runs.
The easiest method is instagram_monitor --setup. The setup wizard checks the settings before saving them. If you allow it to replace an existing configuration, it first creates a backup whose name includes the current date and time. Replacement builds a fresh configuration from defaults, so settings that are not shown by the wizard are reset unless you restore them from the backup.
If you want to edit the file manually, generate a default config template and save it to a file named instagram_monitor.conf:
# 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: In Windows PowerShell, do not use
>for this command. Some PowerShell versions write redirected text as UTF-16, which makes Instagram Monitor report a "null bytes" error. Pass the filename to--generate-configso Instagram Monitor writes a UTF-8 file itself.
When you include the filename, Instagram Monitor writes the template directly as UTF-8. This avoids PowerShell changing the file encoding during redirection.
Open instagram_monitor.conf in a text editor and change the settings you need. The file contains a short explanation above each setting.
Without --config-file, Instagram Monitor uses the first configuration it finds in this order:
instagram_monitor.confin the current directory~/.instagram_monitor.confin the home directoryinstagram_monitor.confnext to the script
An explicit --config-file PATH is always used and the command stops with an error if that file does not exist.
What a Configuration File May Contain¶
A configuration file is a list of settings, not a program. Instagram Monitor reads it without running it, and accepts only lines of the form SETTING = value where the value is plain text, a number, True, False, None, a list, a tuple or a dictionary:
INSTA_CHECK_INTERVAL = 5400
TARGET_USERNAMES = ["user1", "user2"]
COLOR_THEME = { "header": "bright_cyan" }
Imports, function calls, conditions and any other code are rejected, and the setting name must be one Instagram Monitor recognizes. This matters because the first configuration searched is the one in your current directory: without this rule, starting the tool inside a downloaded archive or a shared directory that happened to contain an instagram_monitor.conf would run whatever that file contained.
A rejected file changes nothing. The error names the line and the reason, and no setting from that file is applied.
If the same setting appears in more than one place, the item later in this list wins:
- Built-in defaults
- The discovered or explicitly selected configuration file
- Supported private values from
.envor process environment variables - Command-line options
The .env and process environment layer applies only to SESSION_PASSWORD, SMTP_PASSWORD, WEBHOOK_URL, PROXY_URL and NTFY_ACCESS_TOKEN. For these keys, a value in the selected .env file replaces a value that was already exported in the shell. Use --config-file PATH and --env-file PATH if you do not want automatic file discovery.
Proxy IP Lookup Endpoints¶
When proxy routing is enabled, Instagram Monitor checks the proxy exit address through IP_ADDRESS_URL. The setting accepts one complete HTTP or HTTPS URL or an ordered non-empty list:
IP_ADDRESS_URL = [
"https://checkip.amazonaws.com",
"https://api.ipify.org?format=json",
"https://api.my-ip.io/v2/ip.json",
]
Each retry cycle tries every configured endpoint in order before the long retry delay. A response is accepted only when a recognized JSON field or plain-text body contains a valid IPv4 or IPv6 address. Empty lists, incomplete URLs and URLs with embedded credentials are rejected with an unavailable status instead of crashing monitoring.
Each public lookup service can observe the proxy exit IP. Set one trusted endpoint or a self-hosted service if you do not want fallback requests sent to multiple providers. These lookup requests do not include Instagram session credentials.
Save one or more monitoring targets through setup or set TARGET_USERNAMES yourself:
Usernames written directly after the command and usernames passed through --targets are combined. If the command contains any targets, that combined list replaces TARGET_USERNAMES for that run. To use only the saved targets, run:
You can also change most settings and generate a config file through the Web Dashboard. Targets you add or remove in the browser are saved into TARGET_USERNAMES when you press Generate Config, so the next start monitors the same list.
Target and session usernames may contain 1 to 30 letters, digits, periods or underscores. A leading @ is accepted and removed. Other characters are rejected before monitoring starts so usernames cannot be interpreted as file paths.
No-Login Mode (No Session Login)¶
This mode does not sign in to Instagram. It can monitor new or deleted regular posts, bio changes and follower or following counts for public accounts. Follower and following notifications report count changes without usernames because complete list comparison is unavailable. It cannot monitor reels or stories. It also cannot tell you which specific accounts followed or unfollowed the target.
No-login mode needs no Instagram credentials and makes fewer requests than logged-in mode. Instagram can still limit or block public requests, so this mode does not guarantee uninterrupted access.
Logged-In Mode (With Session Login)¶
This mode signs in with an Instagram account. It can access reels, stories and the usernames added to or removed from follower and following lists.
Logged-in monitoring can cause Instagram to show a security challenge, limit the session or suspend the account. There is no known request rate that guarantees safety. Use a separate Instagram account if losing access to your main account would be unacceptable, then follow the risk reduction guide.
Option 1: Basic Session Login (not recommended)¶
You can provide the session account username and password in instagram_monitor.conf, through an environment variable or with the -u and -p options.
However, this triggers a full login every time the tool runs, increasing the chance of detection and account lockouts.
If SESSION_PASSWORD is in a .env file, a running process on macOS, Linux or Unix can reload it after a SIGHUP signal. See Storing Secrets and Signal Controls.
Option 2: Session Login via Instaloader (better, but can be detected)¶
This method uses the Instaloader command to sign in once and save the resulting session:
Later runs reuse the saved session instead of sending the password again. Instagram can still detect or limit the monitoring requests.
The local command above stores the session in your user profile. Docker containers have a separate file system, so create the session inside the instagram_monitor_session volume that later monitoring runs use:
For a direct image, mount the normal session volume and override the entry point:
docker run --rm -it -v instagram_monitor_session:/home/instagram/.config/instaloader --entrypoint instaloader misiektoja/instagram-monitor:latest -l <your_insta_user>
For device consistency, set USER_AGENT to match Instaloader's Chrome user agent (see User Agent below).
Option 3: Session Login Using Browser Cookies (recommended)¶
This method reuses an Instagram login that already works in a supported browser. Firefox has the widest platform support. Chrome, Brave and Chromium are also supported on macOS and Linux but need an optional package.
Log in to your account (your_insta_user) in the browser, then run:
--browser accepts firefox (default), chrome, brave or chromium. The older --import-firefox-session flag still works as an alias for --browser firefox.
You can also import through the Web Dashboard. Open the Session page, select the browser and click Import. If the browser has several profiles, select the profile that contains the Instagram login you want to use.
The tool reads the cookies from the selected browser profile and saves a session in Instaloader's format. It does not change the browser profile.
Profile selection works the same way for every browser (see Selecting a browser profile below). To pick a specific Firefox profile by name:
On Linux, Firefox profiles installed natively, through Snap or through Flatpak are discovered automatically. You can adjust the default Firefox cookie directory permanently via FIREFOX_*_COOKIE configuration options. The advanced --cookie-file option covers any other layout.
Which browsers are supported¶
The --browser flag (and the dashboard dropdown) accepts these values:
--browser |
Application it reads | Platforms |
|---|---|---|
firefox (default) |
Mozilla Firefox | macOS, Linux, Windows |
chrome |
Google Chrome | macOS, Linux |
brave |
Brave | macOS, Linux |
chromium |
The standalone open-source Chromium browser | macOS, Linux |
About chromium: Chromium is a separate browser application from Google Chrome. It has its own profiles and cookies. Choose chromium only if that is the browser you use. Choose chrome for Google Chrome.
Not currently supported: Microsoft Edge, Opera, Vivaldi, Arc and other Chromium-based browsers. Each application stores its cookies separately. The pycookiecheat library used by Instagram Monitor supports only the browsers in the table. To import a session, log in through one of those supported browsers.
Importing from Chrome, Brave or Chromium¶
Chrome, Brave and Chromium encrypt their cookies. Instagram Monitor uses the optional pycookiecheat package to decrypt them on macOS and Linux. For a PyPI installation, install it with the browser extra:
If you run the downloaded script or installed from requirements.txt, install it directly instead:
Then import the session:
On Windows, Chrome 127 and newer prevent external programs from reading these cookies through app-bound encryption. Use Firefox import instead.
Selecting a browser profile¶
Every supported browser can have several profiles with separate cookies. Use one of these methods:
-
Pick by name with
--browser-profile. Use the Firefox profile name (e.g.default-release) or the Chromium profile directory (e.g.Default,Profile 1): -
Let it prompt you. If you do not pass
--browser-profileand several profiles exist, the tool lists them so you can choose. - On the Web Dashboard, pick the browser, click Import and select a profile if prompted. The dashboard imports only from the profiles it detected, so it cannot be pointed at another file on your computer. Use
--cookie-file PATHon the command line when you deliberately want a database from somewhere else. - Advanced: point
--cookie-fileat a specific cookie database (Firefoxcookies.sqliteor a ChromiumCookiesfile). This overrides--browser-profile.
For Chromium-based browsers, the tool finds the cookie database inside the selected profile. It supports both <profile>/Cookies and <profile>/Network/Cookies layouts.
Chromium-based import does not work inside Docker because the container cannot use the host password service needed to decrypt the cookies. Use Firefox as shown under Container Operation. You can also perform a Chromium import with a local PyPI or manual installation.
Using the account normally in the same browser may help Instagram recognize the session. Avoid using the browser account while Instagram Monitor is making requests because simultaneous activity may look unusual.
User Agent¶
A user agent is text that identifies the browser and operating system making a request. Use the user agent from the same browser profile that supplied the session:
- in Firefox, type
about:supportin the address bar and copy theUser Agentvalue under theApplication Basicssection - in Chrome, Brave or Chromium, open
chrome://versionand copy theUser Agentvalue - set this value through
USER_AGENT, the--user-agentoption or the Web Dashboard
If you created the session with Instaloader instead (Option 2 above), match Instaloader's user agent rather than a browser's. Instaloader logs in with a Chrome user agent, so set USER_AGENT to a matching Chrome string to keep the same device consistency. You can print the exact value Instaloader uses with:
python3 -c "from instaloader.instaloadercontext import default_user_agent; print(default_user_agent())"
With the default auto setting under HTTP Transport Backend, curl_cffi selects a matching browser network profile. For example, a Chrome user agent selects a Chrome profile.
Time Zone¶
Instagram Monitor detects the local time zone automatically. Set LOCAL_TIMEZONE in instagram_monitor.conf if the detected value is wrong or if monitoring should use another time zone:
You can get the list of all time zones supported by pytz like this:
Set TIME_FORMAT_12H = True to display times in 12-hour format instead of the default 24-hour format.
SMTP Settings¶
Email notifications need the SMTP server details for the email account that sends the messages. Add them to instagram_monitor.conf or use the setup wizard.
Send one test message to verify the settings:
Storing Secrets¶
A .env file is a plain text file that holds private values separately from regular configuration. Store SESSION_PASSWORD, SMTP_PASSWORD, WEBHOOK_URL, NTFY_ACCESS_TOKEN and PROXY_URL there. Do not commit this file or share it.
The recommended way to save a Discord or ntfy destination is:
Paste the complete HTTPS URL at the hidden prompt. Instagram Monitor validates it then updates only WEBHOOK_URL in .env without displaying the value. Standard Discord and public ntfy.sh URLs select the matching request format automatically. Configure WEBHOOK_PROVIDER in instagram_monitor.conf for a self-hosted or compatible endpoint. Use --env-file PATH with this command to select another dotenv destination.
You can use operating system environment variables instead of a file. Set them with export on Linux, Unix, macOS or WSL:
export SESSION_PASSWORD="your_instagram_session_password"
export SMTP_PASSWORD="your_smtp_password"
export WEBHOOK_URL="https://discord.com/api/webhooks/..."
export NTFY_ACCESS_TOKEN="tk_your_ntfy_access_token"
On Windows Command Prompt use set instead of export and on Windows PowerShell use $env.
To keep the values between terminal sessions, store them in .env. The repository includes an .env.example template:
This leaves an existing .env untouched, including any secrets saved by the setup wizard.
SESSION_PASSWORD="your_instagram_session_password"
SMTP_PASSWORD="your_smtp_password"
WEBHOOK_URL="https://discord.com/api/webhooks/..."
NTFY_ACCESS_TOKEN="tk_your_ntfy_access_token"
By default, the tool looks for .env in the current directory. If it is not there, the search continues in each parent directory.
Select another file with DOTENV_FILE or --env-file:
You can also disable .env auto-search with DOTENV_FILE = "none" or --env-file none:
As a fallback, you can store secrets in the configuration file. Avoid putting secrets directly in the source code.