RELEASE_NOTES.md

instagram_monitor release notes

This is a high-level summary of the most important changes.

Changes in 4.0.3 (TBD)

Version 4.0.3 makes requests to Instagram look more like a browser's. Calls to the web API no longer carry headers that only a page typed into the address bar would have, and each Instagram session keeps its connection open instead of opening a new one per request.

Features and improvements:

• IMPROVE: Requests closer to a browser's - With the default curl_cffi backend, calls to Instagram's web API went out with the headers of a page typed into the address bar, plus a few headers no browser sends, and every request opened a new connection. They now carry the headers the impersonated browser sends for the site's own background requests, and each Instagram session keeps one connection open between requests. The requests backend is unchanged

Changes in 4.0.2 (22 Sep 2026)

Version 4.0.2 fixes ntfy alerts. Since version 3.9 almost every ntfy alert failed to send because its title starts with an emoji. It also fixes Discord-format alerts that were dropped when a custom header used a placeholder such as {title}.

Bug fixes:

• BUGFIX: ntfy alerts are delivered again - Follower, profile, story, bio and error alerts sent to ntfy failed with 'latin-1' codec can't encode character. The title was sent as a plain HTTP header, which cannot carry emoji or most non-Latin letters. The test webhook still worked because its title has no emoji. Titles, the alert text sent with an image and WEBHOOK_HEADERS values are now sent RFC 2047 encoded when they contain such characters. ntfy shows them as written. A self-hosted server needs ntfy 2.4.0 or newer for titles and alert text and 2.6.2 or newer for custom headers
• BUGFIX: Custom headers with emoji no longer drop Discord-format alerts - With the Discord provider, a WEBHOOK_HEADERS value built from an alert placeholder such as {title} failed the whole alert with the same error. Such values are now sent RFC 2047 encoded (=?UTF-8?B?...?=) and the alert is delivered. A receiver that does not decode RFC 2047 sees the encoded form in that header. ASCII header values and alerts without custom headers are unchanged

Changes in 4.0.1 (22 Sep 2026)

Version 4.0.1 reports unavailable email and webhook settings at startup and skips automatic alerts through those channels until their settings are corrected. It also fixes browser session import: a profile whose Instagram session has expired is no longer marked as signed in, and a failed import names the cause you have to fix. The startup summary now always says whether reels are monitored, a run without a session that Instagram rate limits is told the limit is on its IP address and a failed first check no longer prints its timestamp twice.

Bug fixes:

• BUGFIX: Unavailable alert channels - Selected email and webhook alerts show as unavailable when local delivery settings are missing or invalid. Automatic alerts skip those channels without printing delivery errors. Explicit test commands still report configuration errors. A missing SMTP user or password now points to those credentials instead of unrelated settings.
• BUGFIX: The profile marked as signed in actually is - The * marker, the preselected default and the Web Dashboard listing looked only for a session cookie, so a profile signed out months ago was still offered as the one to import from. Expiry is now read as well, in whichever unit the browser records it. A profile holding only an expired session says so and gives the date, from the cookie database, instead of spending an Instagram request to fail
• BUGFIX: Failed imports name what to fix - A locked Linux keyring reported that the browser was not signed in, sending you to the wrong place. It now says the keyring is locked, or that no keyring backend is installed and points at Firefox, which needs none. A cookie database that cannot be decrypted or opened is named as that rather than as a missing login. The other profiles a failure lists are named the way the picker showed them
• BUGFIX: The startup summary says whether reels are monitored - Reels are off by default, but the Fetch reels row was printed only when they were on, so an ordinary run never showed it. The row is always there now, so a run upgraded from an earlier version can see why its reels stopped arriving
• BUGFIX: Anonymous rate limits get the right advice - A run without a session that Instagram answers with Please wait a few minutes before you try again was told to raise the check interval. That limit is on the IP address, counts everything behind it and is often hit on the very first request, so slowing the run down cannot lift it. The advice now says so, points at a session login, which is limited per account instead, and links a new troubleshooting section
• BUGFIX: A failed first check prints one timestamp - The report closing a first check that failed, for example on a rate limit, ended with the timestamp and separator printed twice

Changes in 4.0 (22 Sep 2026)

Upgrading is strongly recommended. In September 2026 Instagram stopped answering api/v1/users/web_profile_info/ for accounts that are signed in. Version 3.9.1 and earlier read every profile through that endpoint, so a signed-in run on those versions now fails at the first lookup of every target and cannot be fixed by re-importing the session. Version 4.0 reads profiles another way. Runs without a login are not affected.

Version 4.0 reads follower lists over less than half the Instagram requests previous versions needed. It adds follower-list sources, a daily identity budget that is on by default and an account circuit breaker with recovery after session repair. Setup now asks what to collect before asking where to read it from. It also adds private SMTP password entry, clearer Doctor checks and quieter diagnostics, with stronger protection for saved history and credentials. Signed-in monitoring keeps working after Instagram retired the profile endpoint earlier versions depended on. Alert delivery messages stay within the correct check report and alert channels that still use placeholder configuration values are shown as not configured.

Features and improvements:

• NEW: Follower lists over fewer requests - FOLLOW_LIST_SOURCE = "auto" reads lists over REST, which returns 25 accounts per request instead of the 12 the GraphQL queries returned, so a list of 1,000 accounts costs 40 requests instead of 84. GraphQL is retried only for missing or unreadable endpoints. Select graphql or rest explicitly if needed. Lists require a logged-in session and challenges or rate limits never trigger fallback
• NEW: Experimental browser source - FOLLOW_LIST_SOURCE = "browser" requires the playwright extra and an installed browser. It is slower and never selected automatically. Read the browser-source limitations. Thanks to @tomballgithub for validation and feedback
• NEW: Daily identity budget - IDENTITY_BUDGET_PER_DAY limits follower and following name fetching across targets until local midnight. It defaults to 2000, which covers one full follower and following scan of a typical account with room to repeat it. Counts and other activity continue when exhausted and incomplete lists never replace saved history.
• NEW: Account circuit breaker - Enabled by default, CIRCUIT_BREAKER stops all targets using an account after a confirmed challenge, checkpoint or expired session. Fix the account issue and restart or re-import the session to check recovery.
• NEW: Profile URLs as targets - A target may now be a complete profile URL such as https://www.instagram.com/someuser/, in the setup wizard, on the command line and in TARGET_USERNAMES. It is stored as the username.
• NEW: Exposure report - --exposure shows identity usage, failure categories and circuit-breaker state without account names, target names or local paths. It also reports whether the ledger exists yet and whether this run could save it, how much of the daily budget is left and that it resets at local midnight, how many other accounts share the file and how many of them are stopped
• NEW: Private SMTP password setup - --set-smtp-password takes a hidden password and checks it with the mail server before saving. Guided setup also checks email credentials without sending a message
• IMPROVE: Setup and Doctor improvements - Setup preserves saved settings, lets you skip unavailable answers and offers log, CSV and alert choices. Choosing an existing Instaloader session now checks that a session file for that account exists. It also asks whether to collect followers and following, followers only, or counts only with no names, and asks where to read them from only when it will read them.
• IMPROVE: Clearer browser session import - The profile list in setup and on the Web Dashboard marks the profiles signed in to Instagram with *, and defaults to the signed-in one when there is only one. The setup login menu also reports which browsers have a signed-in profile at all, before you choose one.
• IMPROVE: Fewer lookups after a restart, and the daily name cap is asked for - A target's Instagram user id is now written beside the other state files and reused by later runs, so an established target is not looked up again on every start. An id is dropped and resolved again if Instagram reports a different name for it, which is what happens when a username is freed and taken by someone else. A target that is the signed-in account itself takes its id from the session and is never searched for (thanks @VecToR-1024, from #135)
• IMPROVE: Reels can be left alone, and are by default - The endpoint Instagram reports a reel count with has become unreliable, failing regardless of the account or the IP address, and the only way left to get the count is to read the target's whole reel list. Reels are therefore no longer monitored by default. Posts and stories are unaffected, and a reel still counts towards the posts number, so a new reel moves that. Turn reels back on with FETCH_REELS, --fetch-reels, the Web Dashboard or the question --setup now asks, and expect repeated errors on the checks Instagram refuses
• IMPROVE: Reels counts are not recounted every cycle - Instagram stopped answering the endpoint that reports a target's reels count, so the count is worked out by reading the whole reel list. That list is now read again only when the target's posts count moves, which a new reel does
• IMPROVE: Quieter diagnostics and notifications - --verbose reports events and --debug adds technical traces with secrets redacted. Persistent outages produce hourly reminders and recovery notices instead of repeated errors. Set DELIVERY_CONFIRMATIONS = False to hide delivery confirmations while keeping verbose diagnostics.
• IMPROVE: TLS and terminal output - VERIFY_SSL covers outbound certificate checks, including email. Verification is on by default and disabling it produces a warning. --truncate N limits screen width while logs retain full lines. It works without wcwidth, which improves Unicode width measurements.
• IMPROVE: Failure alerts share one shape - Every monitoring failure email and webhook uses the subject Instagram Monitor error: <what went wrong> (user: <target>) and lists the fix, the guide link, how many checks failed in a row, since when and when the next retry happens. A recovery alert follows on the channels that received the failure alert once monitoring resumes. -e / --no-error-notify and --no-webhook-error-notify switch both off

Bug fixes:

• BUGFIX: Signed-in monitoring works again after Instagram retired a profile endpoint - In September 2026 Instagram stopped answering api/v1/users/web_profile_info/ for accounts that are signed in, replying 400 feedback_required however healthy the account was. Every signed-in run failed at the first profile lookup. A signed-in run now resolves the target through Instagram's search and reads the profile over GraphQL, which the same session answers normally. Each target's id is resolved once and reused for the rest of the run. The retired endpoint is still tried for a target search cannot list, and its refusal is now reported as endpoint_retired, which does not stop the account or trip the circuit breaker. Runs without a login were never affected and are unchanged (thanks @VecToR-1024 for an independent fix and validation in #135)
• BUGFIX: Flagged sessions caught across requests - Challenges and feedback requirements during story, post or follower-list requests now pause other targets and trigger account recovery handling, as profile failures do. Fixes #131
• BUGFIX: Firefox from the Microsoft Store is found on Windows - Session import searched only %APPDATA%\Mozilla\Firefox\Profiles, so a machine whose only Firefox came from the Store was told no cookies.sqlite was found. It now also searches the Store package's profile folder under %LOCALAPPDATA%\Packages, follows a redirected APPDATA or LOCALAPPDATA, and lists those profiles as Microsoft Store so the default-release both installs create can be told apart. Container imports mount a single fixed path and still cover the regular installer only (thanks @VecToR-1024, from #134)
• BUGFIX: Story viewing warnings - Stories loaded at startup now carry the same anonymity warning as newly detected stories in both dashboards. The Web Dashboard also warns for older story records and requires confirmation before opening a story, including with a middle-click. Downloaded images offer View Media instead of a broken video control. Play Video uses downloaded videos only.
• BUGFIX: Alert deliveries stay inside their report - The hourly Monitoring degraded reminder closed its report before the error alert was sent, so Sending email notification to ... and its webhook equivalent landed under the separator and started a second, headless block. The reminder now closes below its delivery lines, keeping one check's report in one block
• BUGFIX: Windows Docker Firefox import finds the profiles - The Windows container commands mounted %APPDATA%\Mozilla\Firefox, one level above the Profiles folder the container looks in, so the import reported no cookies.sqlite was found. The commands now mount %APPDATA%\Mozilla\Firefox\Profiles, and a container given the old path still finds the profiles, so a command already saved in a script keeps working
• BUGFIX: Protected follower history - Malformed follower and following records are reported before replacement. Correct the named file or move it aside to start fresh
• BUGFIX: Safer configuration and secret updates - Configuration replacement creates a backup when a filename is passed. Shell redirection bypasses this protection. Setup preserves retained credentials when changing destinations and keeps inline secrets out of configuration backups.
• BUGFIX: Safer notification delivery - Webhook retries keep their original destination and credentials. Discord templates cannot enable mentions and invalid templates are rejected before delivery. Error messages redact credentials, including SMTP rejection replies.
• BUGFIX: Readable ntfy alerts - ntfy notifications arrive as plain text. The bold markers, the backslashes in follower and following names and the brackets around links are gone, since no ntfy client renders the Discord markdown they came from. Discord alerts are unchanged
• BUGFIX: Reported changes name the window they were observed in - The Check interval: line under a change was built from the randomized interval the run was about to sleep, not from the time that had passed, so a change found after a failed check or outside the monitoring hours was reported over a window the tool had not been watching. It now measures from the previous successful check

Security and privacy:

• SECURITY: Private follow-analysis errors - Unexpected Web Dashboard analysis failures no longer return local file details. Use --debug to see the diagnostic locally
• SECURITY: Container security updates - Published rebuilds refresh Debian security updates instead of reusing cached package layers

Smaller fixes and development changes are listed in the full change history.

Changes in 3.9.1 (27 Aug 2026)

Version 3.9.1 makes every published download verifiable, adds automated defect checks on every change, keeps Instagram text safe in the Terminal Dashboard and fixes environment-variable secrets being ignored when no dotenv file is present.

Features and improvements:

• IMPROVE: Verifiable release downloads - Releases now ship a SHA256SUMS.txt and a signed build attestation, including the .intoto.jsonl bundle, checkable with gh attestation verify
• IMPROVE: Automated defect checks on every change - A pinned Ruff lint pass now runs in CI before the test suite, plus optional pre-commit hooks and a shared .editorconfig
• IMPROVE: Corrected and improved wording in setup wizard and doctor preflight

Bug fixes:

• BUGFIX: Disabled alert channels are reported as disabled - --doctor validated a webhook URL and reported the alert choices as valid even when WEBHOOK_ENABLED was False, and offered to send a real test through a channel the user had switched off. It now reports Webhook alerts are disabled and stops there. Email is gated the same way
• BUGFIX: Environment variables work without a dotenv file - Secrets exported as environment variables, such as SESSION_PASSWORD, SMTP_PASSWORD, WEBHOOK_URL or NTFY_ACCESS_TOKEN, were applied only when a dotenv file also existed, so an export-only setup silently fell back to the shipped defaults. They are now honored on their own, including with --env-file none.

Security and privacy:

• SECURITY: Instagram text stays safe in the Terminal Dashboard - Captions, status details and activity messages now have terminal control sequences removed before Rich renders them, so a malicious profile can no longer clear the screen, rename the window or overwrite dashboard text

Changes in 3.9 (22 Aug 2026)

Version 3.9 improves safety and reliability. The Web Dashboard is harder for other websites to reach or control. Its setup can now start with no accounts so you can add them later in your browser. Instagram text is made safe before it appears in your terminal, emails or CSV files. Follow alerts are more reliable when a list is incomplete. Errors explain how to fix the problem. This release also adds offline follow relationship analysis, a security policy and regular security checks.

Features and improvements:

• NEW: Offline follow relationship analysis - Use --analyze-follows or the Web Dashboard chart button to compare follower and following lists you already saved. It shows mutual accounts, accounts that do not follow you back and fans without contacting Instagram. It shows when each list was saved and warns if they are more than an hour apart. Totals include every account. The two username lists show up to 500 accounts each (thanks @dogukannparlak, from #121)
• IMPROVE: Errors that tell you what to do - Monitoring errors now end with a To fix: action and a Guide: link where available. DNS errors say when the tool cannot find www.instagram.com instead of showing a vague network error. Monitoring automatically continues when DNS starts working. Use --debug to see the technical details
• IMPROVE: Doctor works with a broken setup - --doctor now reports an invalid configuration as FAIL with the line number and reason. It keeps running so you can check a file you are fixing. It also checks SENDER_EMAIL and RECEIVER_EMAIL before connecting. Placeholder email addresses no longer pass the email test then fail on every notification. The progress line also redraws cleanly
• IMPROVE: Lighter human mode - The BeHuman followee visit now checks only the first page of accounts your session follows before choosing one. This greatly reduces extra Instagram requests for accounts that follow thousands of people
• IMPROVE: Faster monitoring of multiple targets - A target can now start fetching while another target shows a follower-download progress bar. It fetches without a second bar instead of waiting for the first download to finish
• IMPROVE: Clearer ntfy customization - Generated configuration now explains that WEBHOOK_TEMPLATE, WEBHOOK_USERNAME and WEBHOOK_AVATAR_URL work only with Discord. ntfy does not use a template. For ntfy options such as priority or tags use WEBHOOK_HEADERS
• IMPROVE: Clearer issue reports and contribution guide - New issue forms ask for the version, install method, operating system, login method and --doctor output. Security problems are directed to private reporting. New CONTRIBUTING.md, CODE_OF_CONDUCT.md and a pull request template explain how to contribute
• IMPROVE: Published security policy - SECURITY.md explains how to report a security problem privately through GitHub security advisories. It also explains which versions receive fixes and safe deployment basics: keep the password-free Web Dashboard on your own machine, store secrets in owner-only .env files and use configuration files only for settings
• IMPROVE: Clearer dependency and security checks - New THIRD_PARTY_NOTICES.md lists each dependency, its license and why the project uses it. Automated checks look for known vulnerable dependencies, create a list of installed components, scan the container image and scan the source code. They run on every change and weekly, so newly reported problems can still be found

Bug fixes:

• BUGFIX: Reliable follower and following alerts - The tool now ignores a changed follower count only after a complete list comparison confirms that no usernames changed. No-login mode, skipped or failed downloads and configured download limits still alert about count changes. An incomplete download is no longer saved as the new comparison list. The tool now also logs Followers list changed when one person follows and another unfollows between checks (@stdpankaj, closes #118 and #119)
• BUGFIX: Working webhook tests - --send-test-webhook and the dashboard Test Webhook button now send a test message even when all event notifications are off. A default your_webhook_url value is treated as not configured. Normal event notifications still follow your settings. Use --debug to learn why a notification was skipped
• BUGFIX: Human mode without hashtags - An empty MY_HASHTAGS setting now skips only hashtag browsing. The Explore, profile and followee actions still run
• BUGFIX: Stable long-running dashboard sessions - Repeated dashboard setting or session changes no longer build up until they stop a monitor. Restarting after a flagged session also keeps your SKIP_FOLLOW_CHANGES choice. A target that is still stopping cannot start a duplicate monitor
• BUGFIX: Safer live setting changes - The Web Dashboard now rejects invalid values before changing a live setting. This includes unsafe URLs, invalid ports, invalid intervals and invalid hour ranges. Unsupported CURL_CFFI_IMPERSONATE or --impersonate values now name the supported choices instead of causing a vague connection error
• BUGFIX: Reliable media downloads and dashboard links - Images and videos are checked before they replace an existing saved file. Incomplete downloads, files that are too large and HTML error pages leave the existing file unchanged. Each story, post or reel now starts with a clean media record. Story webhooks no longer depend on email settings. Recently updated media stays in the dashboard even after it reaches 1,000 items
• BUGFIX: Older configuration files keep loading - Configuration files made by version 3.0 now start normally. Settings removed or renamed in later versions are ignored with a note that tells you which lines to delete. Misspelled settings are still reported as errors
• BUGFIX: Startup settings apply immediately - CLEAR_SCREEN = False now stops the startup screen clear. COLORED_OUTPUT now applies to the startup banner. The startup internet check now uses your CHECK_INTERNET_URL and CHECK_INTERNET_TIMEOUT values
• BUGFIX: Faster recovery from a flagged session - When several targets see the same blocked session or IP address, they now share the first result instead of each waiting for its own Instagram request. Long Instagram waits no longer delay webhooks, media downloads or proxy and IP checks
• BUGFIX: Terminal restored after quitting the dashboard - Pressing q or Ctrl+C now restores normal terminal typing before the tool exits
• BUGFIX: Accurate dashboard startup errors - The tool reports a port conflict only when the address is actually in use or refused. Other startup errors show their real cause
• BUGFIX: Dashboard targets survive a restart - Targets added or removed in the browser are now saved to TARGET_USERNAMES when you press Generate Config. A restarted service therefore monitors the same list. The confirmation shows the full file path so you can see when a service started in / is not updating the file passed to --config-file (closes #122)
• BUGFIX: Target-free dashboard setup - Leave the setup wizard's target question empty to start with only the Web Dashboard then add accounts in your browser. Terminal Dashboard and plain-text setups still require at least one target

Security and privacy:

• SECURITY: The Web Dashboard accepts only your requests - The dashboard now accepts requests only for 127.0.0.1, localhost, ::1 or your configured WEB_DASHBOARD_HOST. This stops a malicious website from using your browser to control the dashboard. Changes such as stopping monitoring, requesting extra checks, clearing the activity log or sending a test notification must come from the dashboard page itself. Use WEB_DASHBOARD_ALLOWED_HOSTS to add names you intentionally use. Setting it to "*" restores the old behavior. Scripts can still use 127.0.0.1 with a JSON request
• SECURITY: Saved credentials stay with the right server - If you change SMTP_HOST or SMTP_PORT without entering the password again, the dashboard removes the saved SMTP password. Enter it again in the same save to keep email working. Changing WEBHOOK_URL to a different server also removes NTFY_ACCESS_TOKEN. Changing only an ntfy topic on the same server keeps the token
• SECURITY: Opening the dashboard does not contact Instagram - The Last Fetched panel shows a thumbnail only when the monitor already saved it on your machine. Opening the dashboard no longer tells Instagram your IP address or which accounts you watch. Failed downloads show a placeholder. Instagram links are also checked before display so they cannot run code in your browser
• SECURITY: Safer dashboard input - Generated configuration files must use a *.conf name. The dashboard cannot overwrite scripts or hidden files in your working directory. It accepts only valid view options and safe media file names. It imports Firefox cookies only from profiles it found and only for real instagram.com addresses. The dashboard shows media only when the monitor registered the file. It never returns webhook or proxy URLs in settings data. The CSV file name field accepts a file name only. An absolute CSV_FILE path in the configuration or -b still works
• SECURITY: Configuration files contain settings only - The tool now reads configuration files as settings. It does not run them as Python code. Only known SETTING = value lines with plain values are accepted. Imports, function calls and other code are rejected with the line number. A rejected file changes nothing. This protects you when you start the tool in a downloaded archive or shared directory. Existing valid configuration files still work
• SECURITY: Instagram text cannot control your terminal or files - The tool removes special terminal commands from biographies, captions, story text, comments and usernames before printing or logging them. A malicious profile cannot clear your screen, rename your terminal window or overwrite text you already read. Text that could act as a spreadsheet formula is saved safely in CSV files. Email alerts also display this text safely. IMGCAT_PATH now opens its image viewer without creating a shell command
• SECURITY: Notification text stays out of web addresses - ntfy messages are sent in request headers or the request body instead of the web address. This avoids putting follower names, captions or biographies in URLs that servers and proxies often log. Webhooks now require HTTPS, check certificates and do not follow redirects. A changed destination cannot receive custom WEBHOOK_HEADERS meant for the original address
• SECURITY: Private configuration backups - Configuration backups made by the setup wizard or --generate-config now stay owner-only and keep the original file's permissions
• SECURITY: Safer container and release builds - Container images now remove pip and build-only packages after installation. This reduces the installed software and removes known high-severity issues. When you start the dashboard in Docker, the tool now explains that Docker uses 0.0.0.0 inside the container. It shows -p 127.0.0.1:PORT:PORT to keep the dashboard on your machine and warns before you expose it publicly. Automated project jobs use fixed versions of third-party actions so a changed tag cannot alter the release process

Changes in 3.8.1 (04 Aug 2026)

Version 3.8.1 streamlines first-time setup and diagnostics, adds portable logs and prevents webhook noise from repeated monitoring failures.

Features and improvements:

• IMPROVE: Clear timezone recovery - When automatic detection fails, the startup error now identifies the optional tzlocal dependency, shows how to install it and explains that LOCAL_TIMEZONE can be set manually
• IMPROVE: Portable log separators - The new ASCII_LOG_SEPARATORS setting controls whether separator-only lines saved to log files use ASCII hyphens. "Auto" enables them on Windows by default, "On" enables them on every operating system and "Off" preserves Unicode separators. Terminal separators stay Unicode. Log files and all other logged text remain UTF-8.
• IMPROVE: Flexible setup intervals - The setup wizard accepts polling interval durations such as 30s, 2m, 1.5h, 1h 30m and 1d while still saving the value as seconds
• IMPROVE: Actionable Doctor output - Details remain attached to their checks, final target-specific log destinations are validated and pycookiecheat is clearly identified as a Chromium-only import dependency that Firefox does not need
• IMPROVE: Beginner Python installation walkthroughs - New Windows, macOS and Linux instructions guide first-time Python users from checking prerequisites through installation and the setup wizard

Bug fixes:

• BUGFIX: Thresholded monitoring alerts - ERROR_FAILURE_THRESHOLD now applies consistently to email and webhook errors so repeated session failures alert once at the configured count instead of sending a webhook on every retry. Alerts for flagged sessions remain immediate (closes #116)

Changes in 3.8 (30 Jul 2026)

Version 3.8 strengthens Discord and ntfy webhook delivery, adds safer private URL setup, improves proxy IP detection and brings better notification controls.

Features and improvements:

• IMPROVE: Added ordered proxy IP lookup fallback endpoints with backward-compatible single-URL configuration, IPv4 and IPv6 validation plus documented privacy controls (thanks @tomballgithub, from #113)
• NEW: Added private webhook URL setup through --set-webhook-url with hidden entry and complete HTTPS destination validation
• IMPROVE: Added stricter webhook request validation for destinations, avatars, templates, transforms and expanded headers plus Discord mention suppression
• IMPROVE: Added bounded webhook delivery with isolated requests, capped rate-limit delays, one retry for temporary failures and automatic provider correction across CLI, Doctor and Web Dashboard flows
• IMPROVE: Added native ntfy image attachments with a 5 MiB limit and automatic text-only fallback when image preparation or upload fails
• IMPROVE: Made the status, follower and error webhook controls enable webhook delivery for the current run
• IMPROVE: Split the startup notification summary into compact email and webhook rows across concise, verbose and logged views

Bug fixes:

• BUGFIX: Stopped startup summaries and Web Dashboard setting-change logs from writing private webhook URLs to logs
• BUGFIX: Kept long ntfy messages below its 4 KB attachment boundary, added a visible truncation explanation and preserved complete UTF-8 characters
• BUGFIX: Restored green On and red Off status cues in compact notification rows without coloring category text
• BUGFIX: Made SIGHUP apply rotated proxy credentials to active Instaloader sessions and redetect Discord or ntfy when the private webhook destination changes
• BUGFIX: Made proxy IP failover try every configured endpoint before the long retry delay, reject invalid successful responses without crashing and preserve custom endpoint lists in generated configuration

Changes in 3.7.1 (24 Jul 2026)

Bug fixes:

• BUGFIX: Updated the built-in guide link to the renamed Setup & First Run page so CLI help and recovery guidance no longer point to the retired Quick Start URL

Changes in 3.7 (23 Jul 2026)

Version 3.7 makes Docker onboarding portable across macOS, Linux and Windows. It adds host-aware Firefox session import and keeps setup files safe on the persistent /data bind mount. Generated recovery commands now preserve targets, custom files and Web Dashboard ports from import through Doctor and launch.

Features and improvements:

• IMPROVE: Kept Firefox session import as the recommended Docker setup choice while deferring the import until setup files are saved. The wizard now asks which host environment runs Docker then prints the matching read-only import command for macOS, standard Linux, Snap, Flatpak, Windows PowerShell or Windows Command Prompt
• NEW: Added Windows-host Firefox session import for direct Docker and Docker Compose through the normal %APPDATA%\Mozilla\Firefox profile root with shell-specific PowerShell and Command Prompt commands
• IMPROVE: Expanded direct Docker and Docker Compose Firefox import documentation with complete commands for every supported host profile layout
• IMPROVE: Preserved setup guidance across one-time session imports by keeping terminal history visible and repeating the exact Doctor and monitoring commands after a successful Firefox import
• IMPROVE: Printed the install-aware monitoring command after a successful Doctor run while preserving explicit targets, selected files and Web Dashboard port publishing

Bug fixes:

• BUGFIX: Stopped the setup wizard from offering Doctor before a deferred Firefox session import succeeds, avoiding expected authentication failures during incomplete Docker setup
• BUGFIX: Removed Linux user mapping from generated macOS Docker commands while preserving host UID and GID mapping for Linux commands
• BUGFIX: Anchored default container setup files to the bind-mounted /data directory so the generated configuration and dotenv files survive the temporary setup container
• BUGFIX: Preserved Web Dashboard port publishing in Docker and Docker Compose monitoring commands printed after Firefox import then replaced container-only 0.0.0.0 browser links with the reachable loopback URL
• BUGFIX: Rejected Docker setup destinations outside /data instead of saving ephemeral files then printing commands for different paths
• BUGFIX: Generated direct Docker commands with ${PWD} for macOS, Linux and Windows PowerShell then switched to %cd% for Windows Command Prompt while retaining Linux user mapping
• BUGFIX: Prevented local setup from offering immediate monitoring after a declined or failed browser import unless Doctor validates an existing session
• BUGFIX: Rejected conflicting standalone actions and setup targets instead of silently ignoring part of the command
• BUGFIX: Matched generated Docker and one-off Compose port publishing to a non-default Web Dashboard port
• BUGFIX: Restricted terminal time highlighting to valid complete clock values so Docker mappings such as 8000:8000 are no longer partially colored as dates
• BUGFIX: Prevented a Windows traceback after Ctrl+C when monitoring was started directly from setup. The setup parent now treats its duplicate console interrupt as the same clean termination already handled by the monitoring child

Changes in 3.6.1 (22 Jul 2026)

Features and improvements:

• IMPROVE: Added automatic Firefox profile discovery for native Linux, Snap and Flatpak installations. CLI and Web Dashboard session imports now locate all three layouts and de-duplicate cookie databases
• IMPROVE: Improved CLI and --doctor recovery guidance with installation-aware Firefox session import commands and direct links for session, rate-limit, proxy, SMTP, webhook and configuration errors

Bug fixes:

• BUGFIX: Made the Compose service pass /data/.env explicitly so docker compose up loads saved secrets even when config does not set DOTENV_FILE

Changes in 3.6 (22 Jul 2026)

Version 3.6 focuses on flexible, dependable notifications and safer guided configuration. It adds native ntfy support with protected-topic authentication, interactive delivery checks in --doctor and an editable setup summary, while preserving Discord compatibility and strengthening Docker defaults, saved launch behavior and Web Dashboard exposure.

Features and Improvements:

• NEW: Added native ntfy webhook notifications for status, follower and error events. Set WEBHOOK_PROVIDER = "ntfy" and save a complete ntfy topic URL in WEBHOOK_URL or select ntfy in the setup wizard or Web Dashboard. The setup wizard also accepts a bare ntfy.sh topic name and expands it to a complete URL
• NEW: Added authentication for protected ntfy topics via NTFY_ACCESS_TOKEN support with Bearer authentication, hidden setup wizard collection and precedence over custom Authorization headers in WEBHOOK_HEADERS
• IMPROVE: Preserved Discord as the default webhook provider for backward compatibility, including custom payload templates, headers, transformations, proxy routing and Discord image attachments
• IMPROVE: Added provider validation to --doctor, provider visibility in startup and dashboard summaries plus a --webhook-provider {discord,ntfy} command-line option
• IMPROVE: Extended interactive --doctor runs with separate tests for email and webhook channels. Each approved test sends one real message. Doctor never writes files and non-interactive runs remain message-free
• IMPROVE: Sent native ntfy messages as bounded UTF-8 text with the alert subject as the title, event field details in the body and existing topic query parameters preserved for authentication
• IMPROVE: Added an editable setup summary so answers can be reviewed before saving
• IMPROVE: Simplified browser onboarding with separate Firefox and Chromium choices plus optional pycookiecheat installation
• IMPROVE: Made generated commands portable across Python installations and custom config paths
• IMPROVE: Added confirmation, backups and validation when replacing configuration files
• BUGFIX: No-argument launches now honor saved targets and Web Dashboard mode
• BUGFIX: Improved Docker and Compose support for Linux user mappings, persistent sessions and saved interface choices
• SECURITY: Limited Docker Web Dashboard publishing to the host loopback interface

Changes in 3.5 (01 Jul 2026)

Version 3.5 focuses on making the tool easier to use, configure and recover when something goes wrong, especially for non-technical users who asked for a simpler path. It brings guided setup, broader browser-session import, clearer diagnostics and friendlier recovery hints so first runs and everyday troubleshooting require less manual digging.

Features and Improvements:

• NEW: Added an interactive setup wizard to make first-time setup easy for non-technical users. Run it with the --setup flag or launch the tool with no arguments from an interactive terminal and accept the prompt. The wizard asks a short series of questions, then writes a ready-to-run instagram_monitor.conf, routes secrets to a .env file and can start monitoring right away for local installs. It auto-detects whether the tool was installed via pip, run from a downloaded script, run under Docker or run via Docker Compose and tailors the suggested commands accordingly
• NEW: Added session import from Chromium-based browsers (Chrome, Brave and Chromium) in addition to Firefox, via the new --import-browser-session --browser {firefox,chrome,brave,chromium} flags and a browser dropdown on the Web Dashboard Session page. Firefox stays the recommended source as it requires no additional dependencies, while Chromium-based browsers use the optional pycookiecheat package and work on macOS and Linux only. On Windows, where Chrome's app-bound encryption (Chrome 127+) blocks external cookie access, the tool detects the platform and recommends Firefox instead.
• NEW: Added unified per-profile selection across all browsers. A single --browser-profile flag now picks a profile for any browser - a Firefox profile name (e.g. default-release) or a Chromium profile directory (e.g. Default, Profile 1) - with an interactive prompt when several exist and a profile picker on the Web Dashboard import flow. --cookie-file is the advanced explicit-database override for every browser. For Chromium-based browsers the cookie database is resolved directly, so both the legacy <profile>/Cookies and the newer <profile>/Network/Cookies layouts work
• NEW: Added an ASCII art startup banner that prints on launch. It uses pure ASCII for broad terminal compatibility and follows the configured color theme, replacing the previous plain one-line version header
• IMPROVE: The startup summary now prints a concise view on the terminal that leads with the monitored targets and hides settings left at their default or turned off, so the banner stays on screen and the key details (targets, session mode, polling interval, where output goes) are no longer buried in noise. The full configuration is still written to the log for troubleshooting and can be shown on the terminal with --verbose/--debug
• NEW: Added an animated demo (install, setup wizard and run) at the top of the README and docs home, generated from a committed VHS tape (demo.tape) so it can be re-rendered as the tool evolves
• NEW: Added a docker-compose.yml and a .env.example so Docker users can get started with docker compose up instead of long docker run commands, with secrets kept in a copyable dotenv template
• IMPROVE: Running the tool with no arguments from an interactive terminal now shows a short welcome with the most common commands and an offer to launch the setup wizard, instead of dumping the full help text
• NEW: Published a documentation site at misiektoja.github.io/instagram_monitor, built with MkDocs Material and deployed via GitHub Actions. The README is now a concise landing page and the full reference guide
• IMPROVE: The Web Dashboard now shows an actionable "No targets yet" empty state with an Add Target button instead of a permanent "Loading targets..." placeholder when no targets are configured
• IMPROVE: A broken hand-edited config file now reports the offending line and a To fix: hint instead of a raw traceback
• NEW: Added a --doctor preflight self-check. Version 3.5 introduced it as a read-only PASS/WARN/FAIL report with no email or webhook delivery. It covers optional dependencies, the config file and secrets, session validity, Instagram connectivity, target resolution and notification configuration with a To fix: next step on each failure plus a non-zero exit code if any check fails. The setup wizard offers to run it at the end
• IMPROVE: Added action-oriented error hints. Common failures (invalid or expired session, challenge/checkpoint, rate limiting, missing session file, target not found, network problems, SMTP and webhook delivery errors) now print a concise To fix: next step instead of just the raw error
• IMPROVE: Renamed the session modes from numbered Mode 1 / Mode 2 to intent-based No-login and Logged-in across console output, the Web Dashboard, the config template and the README, so you no longer have to remember which number means what
• IMPROVE: Added an examples section to --help with copy-pasteable commands for guided setup, anonymous tracking, logged-in tracking and the web dashboard. The examples auto-detect how the tool was launched (pip, downloaded script, Docker or Docker Compose) and print matching commands the same way the setup wizard does
• IMPROVE: The old --import-firefox-session flag is kept as a backward-compatible alias for --import-browser-session --browser firefox
• IMPROVE: Expanded the offline pytest suite to increase coverage of critical monitoring workflows, including webhook delivery, paginated follower/following fetching, Web Dashboard endpoints, posts/reels count detection, leaked-collab reporting, profile-picture creation/removal/change handling, install-method detection and startup story item metadata/CSV updates.
• IMPROVE: Suppressed Instaloader's intermittent retry noise (the repeated JSON Query to graphql/query: 403 Forbidden ... lines it prints to stderr) during normal runs and the --doctor/--setup preflight, since those attempts usually succeed on a later try. The final failure is still shown, while verbose or debug mode keeps the full chatter

Bug fixes:

• BUGFIX: Repaired logged-in post and reel fetching after Instagram retired the GraphQL doc_id 8845758582119845 (xdt_shortcode_media) in June 2026, which returned null data and crashed Post._obtain_metadata with TypeError: 'NoneType' object is not subscriptable as soon as a field outside the timeline node (such as tagged users) was read. Added a compatibility patch that migrates to doc_id 27128499623469141 (PolarisPostRootQuery) and reshapes the response to the legacy fields (ports instaloader/instaloader#2706, see #2704)
• BUGFIX: Guarded latest_post_reel against a null GraphQL data response so a deprecated query or a temporary block surfaces a clean, actionable To fix: message instead of a raw TypeError

Changes in 3.4 (16 Jun 2026)

Features and Improvements:

• NEW: Added a pluggable HTTP transport backend with browser TLS (JA3/JA4) impersonation via curl_cffi, now the default, to avoid fingerprint-based blocks where Instagram returns a spurious HTTP 429 on the very first request even from a clean IP (most often on Linux OS TLS stacks whose fingerprint Instagram treats as automation). Both the anonymous and logged-in paths use the selected backend and it transparently falls back to requests when curl_cffi is unavailable. Configurable via the HTTP_BACKEND / CURL_CFFI_IMPERSONATE config options or the --http-backend / --impersonate flags, with CURL_CFFI_IMPERSONATE defaulting to auto so the impersonated browser is aligned with the configured user agent, keeping the TLS and client-hint headers consistent (including with a Firefox-imported session)
• NEW: Added detection of leaked collab posts on private accounts (enabled by default). When a private account co-authors a post with a public account, that post stays visible in the private account's timeline media via the public web_profile_info endpoint. The monitor surfaces these otherwise hidden posts (with owner, collaborators, media download and notifications) and reports new ones over time, even for accounts you do not follow. Only probes accounts whose posts are not otherwise viewable. Disable via the DETECT_COLLAB_POSTS config option or the --no-detect-collab-posts flag. Inspired by InstagramPrivSniffer
• IMPROVE: The anonymous post path now populates tagged users and co-authors from web_profile_info instead of leaving the list empty
• IMPROVE: Centralized repeated timestamp label and newline handling in print_cur_ts() (thanks @tomballgithub, from #100)
• IMPROVE: Added Jinja2 as a direct dependency for Web Dashboard template rendering

Bug fixes:

• BUGFIX: Fixed the configured proxy and TLS certificate settings being dropped on the anonymous mobile profile lookup (web_profile_info), which caused that request to bypass the proxy and go out over the real IP
• BUGFIX: Restored the progress bar unit label after paused follower/following batch waits so later progress output keeps the expected label (thanks @tomballgithub, from #103)
• BUGFIX: Fixed flagged-account detection not sending email or webhook alerts. The notification was gated behind ERROR_FAILURE_THRESHOLD so the script terminated before the count was reached. A flagged session or IP now alerts the operator immediately, bypassing the threshold and de-duped so one shared flag alerts once across all monitored targets (fixes #108)

Changes in 3.3 (01 Jun 2026)

Huge thanks to everyone who contributed to this release, with a special shout-out to @tomballgithub who drove most of the work behind these changes and to @BlueXAyman for the Instaloader GraphQL profile metadata patch.

Features and Improvements:

• NEW: Added proxy support for routing Instagram and webhook traffic through a proxy, with an optional client certificate, automatic masking of proxy credentials in output, runtime toggling without a restart and support for multiple IP-lookup services (--enable-proxy / --proxy-url / --proxy-cert / --enable-proxy-webhooks flags or the matching PROXY_* config options)
• NEW: Added privacy substitution support to redact or replace monitored target identities (display names, usernames, captions) across console output, logs, dashboards and webhook payloads, applied at display time so the real identity is never leaked
• NEW: Added shadowban and flagged-account detection, including a canonical-account probe that distinguishes a removed or renamed account from a temporarily flagged one and smarter logic on whether to keep idling or exit while an account is flagged (closes #78)
• NEW: Added advanced control over fetching followers and followings, with batched fetching, configurable total limits and correct handling of stop and recheck events during long fetches
• NEW: Added a SKIP_WRAP_MESSAGES config option to suppress the wrap messages emitted during request monkey-patching
• IMPROVE: Hardened IP-address lookups with retries, interruptible backoff waits and credential masking, plus extra retries when the proxy is temporarily unavailable
• IMPROVE: Switched elapsed-time tracking to a monotonic timer for accurate runtime statistics
• IMPROVE: Refined the progress bar: fit its text during PAUSE, show remaining time above two hours in hours rather than minutes, drop decimals from minute and hour values and handle PAUSED states more robustly
• IMPROVE: Hardened type handling across the code base to satisfy static type checking with pyright
• IMPROVE: Enforced gitleaks secret scanning in CI, added Dependabot version updates and bumped the Docker base image and GitHub Actions dependencies
• IMPROVE: Added an offline test suite (pytest) covering config parsing, time formatting, scheduling windows, privacy substitutions, notification helpers, follower diffing, CSV writing and session-flag detection, with no network access, running automatically in CI across Python 3.9 to 3.14

Bug fixes:

• BUGFIX: Added a compatibility patch for Instaloader GraphQL profile metadata to fix 400 Bad Request on GraphQL query: invalid request when using session mode
• BUGFIX: Decoupled follower/following webhook notifications from the email notification flags so they fire independently and only when something actually changed
• BUGFIX: Fixed hours_to_check() behavior when the feature is disabled (fixes #80)
• BUGFIX: Guarded against posts_count being None during post-count comparisons
• BUGFIX: Hardened update_ui_data debug formatting against non-dict payloads

Changes in 3.2 (10 Apr 2026)

Features and Improvements:

• NEW: Added Docker support with a slim runtime image (closes #13 and #75)
• NEW: Implemented separate error counters for BeHuman simulation and the main monitoring loop
• IMPROVE: Added configurable failure threshold and improved alerting for Instagram human mode issues (closes #63)
• IMPROVE: Improved progress bar stability and output handling with thread-safe suppression and safer width bounds (thanks @tomballgithub, from #69)
• IMPROVE: Improved progress bar ETA and rate calculations for early updates (thanks @tomballgithub, from #69)
• IMPROVE: Suppressed noisy TLS-on-HTTP Werkzeug parse logs in console output (fixes #67)
• IMPROVE: Added GitHub Actions workflow for publishing packages to PyPI and auto-building/attaching zip and tar.gz assets to published releases

Bug fixes:

• BUGFIX: Used nominal interval for human-mode probability on restricted schedules (fixes #64)
• BUGFIX: Triggered error notifications exactly at the configured failure threshold (fixes #71)
• BUGFIX: Made single-target recheck state consistent and returned accurate recheck-all status (fixes #68)
• BUGFIX: Avoided joining current or main thread in target stop path (fixes #73)
• BUGFIX: Normalized non-ASCII characters to avoid output issues (fixes #76)
• BUGFIX: Ensured request monkey-patch is applied when progress bar setup is initialized (fixes #77)
• BUGFIX: Made requests monkey-patch setup thread-safe for progress bar jitter and serialized HTTP paths
• BUGFIX: Restored anonymous profile lookup on Instaloader 4.15.1 via web_profile_info fallback

Changes in 3.1 (07 Feb 2026)

Features and Improvements:

• NEW: Implemented custom webhook configuration support allowing custom templates and headers, defaults to Discord compatibility (thanks @tomballgithub);
• IMPROVE: Enhanced request jitter with exponential backoff and improved 429 error handling
• IMPROVE: Improved webhook robustness with retries and custom User-Agent
• IMPROVE: Updated human mode display to include verbosity option
• IMPROVE: Updated webhook URL validation to accept both HTTP and HTTPS schemes

Bug fixes:

• BUGFIX: Corrected timestamp issue in debug mode (fixes #62)
• BUGFIX: Prevented deadlock in close_pbar by making STDOUT_LOCK re-entrant (fixes #60)
• BUGFIX: Ensured verbose flags display messages independently of debug mode (fixes #59)
• BUGFIX: Handled empty caption edges in mobile API to prevent index error in anonymous mode
• BUGFIX: Added input validation bounds, safe thread cleanup and reels_count null checks

Changes in 3.0 (23 Jan 2026)

Welcome to version 3.0 — our biggest and most ambitious release to date! This update introduces a completely redesigned experience with a powerful new Dual Dashboard system (Web and Terminal), Webhook / Discord notifications, native Color support, custom Output directory feature and advanced Follower Churn detection.

A huge thank you to our amazing contributors @Sha-Dox, @tomballgithub, @YouveGotMeowxy and @jl-nr for their invaluable code, ideas and testing that made this release possible.

Features and Improvements:

• NEW: Added a comprehensive dashboard system accessible in terminal and web, including a Rich-powered Terminal Dashboard and a Flask-powered Web Dashboard with real-time stats, activity feeds and interactive controls; check the Terminal Dashboard and Web Dashboard for more info
• NEW: Added webhook notifications system compatible with Discord and other webhook services for all monitored events with support for sending local image files; check the Webhook Notifications for more info
• NEW: Implemented native color output support for terminal, enhancing user experience with customizable color themes (see COLORED_OUTPUT and COLOR_THEME config options). You can still use the old grc method if you prefer to only color the logs
• NEW: Added follower churn detection (--followers-churn flag or FOLLOWERS_CHURN_DETECTION config option) - forces the tool to download and compare the full list of followers/followings even if the total count hasn't changed, allowing the detection of user handle changes or simultaneous additions and removals; check the Follower Churn Detection for more info
• NEW: Added custom output directory feature to organize all files into target-specific subdirectories (images, videos, logs, json, csvs) which significantly improves organization for multi-target monitoring; check the Output Directory for more info (closes #35)
• NEW: Added skip follow changes option (--skip-follow-changes flag or SKIP_FOLLOW_CHANGES config option) - allows to completely silence and disable follow-related tracking (console prints, activity logs, email/webhook notifications and CSV saving) while still maintaining live statistics in the dashboards; note that enabling this automatically disables follower churn detection as detailed tracking is suppressed; check the Skipping Follow Changes for more info
• NEW: Implemented debug mode (--debug flag or DEBUG_MODE config option) - provides full technical logging including every API request and internal state changes
• NEW: Introduced verbose mode (--verbose flag or VERBOSE_MODE config option) - provides a middle-ground logging level that shows timing details, next check schedule and loop completion messages without the exhaustive detail of Debug Mode
• NEW: Added support for 12-hour time format (TIME_FORMAT_12H config option) across the entire tool including dashboards, console output, activity logs and email notifications
• NEW: Implemented HTML formatting for email notifications for better readability
• NEW: Added dashboard view modes - toggle between 'User' and 'Config' modes across both dashboards with a single keypress ('m') or button click; includes synchronized state throughout the tool
• NEW: Implemented per-target logging - in multi-target mode, each user gets their own log file; common messages (like the summary screen) are automatically broadcasted to all active logs
• IMPROVE: Enhanced CSV path resolution - CSV files are now automatically placed in a csvs/ subdirectory when OUTPUT_DIR and relative path is used. In multi-target mode, the tool always enforces per-user files (even with absolute paths) to ensure data isolation
• IMPROVE: Enhanced CHECK_POSTS_IN_HOURS_RANGE logic to support disabling hour ranges and updated status message (to disable any range, set both MIN and MAXto 0);

... and many other improvements (check the list of commits for the release if you are interested)

Bug fixes:

• BUGFIX: Fixed recent post detection logic in anonymous mode (fixes #34)
• BUGFIX: Expanded tabs to spaces in log files for consistent alignment

Changes in 2.0.4 (04 Jan 2026)

Features and Improvements:

• IMPROVE: standardized visual appearance of progress bar to unify its width in both terminal and log files

Bug fixes:

• BUGFIX: Fixed progress bar display issues - Ensured close_pbar() is called before any print statements in the try block to prevent interleaved output and duplicate progress bars (thanks @tomballgithub)

Changes in 2.0.3 (03 Jan 2026)

Features and Improvements:

• NEW: Multi-user monitoring in a single process - Monitor multiple Instagram users simultaneously without spawning separate processes. Simply pass multiple usernames as arguments or use the --targets flag with comma-separated values
• NEW: Automatic request staggering - When monitoring multiple users, requests are automatically spread across the check interval to avoid triggering Instagram's anti-bot mechanisms. Configurable via MULTI_TARGET_STAGGER or --targets-stagger flag
• NEW: Progress bar for downloading followers/followings - When fetching lists of followers or followings, a real-time progress bar is displayed showing download progress, statistics (names per request, total requests, elapsed time, estimated remaining time) and completion status. Progress updates are shown in the terminal only (to avoid log file clutter), with the final state written to the log file for reference (thanks @tomballgithub)
• NEW: Per-user CSV files in multi-target mode - When monitoring multiple users, each user gets their own CSV file (e.g., instagram_data_user1.csv, instagram_data_user2.csv) using the configured CSV filename as a prefix. Single-user mode continues to use the exact filename specified
• NEW: Improved log file naming - Multi-target log files now use sorted usernames joined with underscores (e.g., instagram_monitor_user1_user2_user3.log), preventing filename collisions when monitoring different user sets
• NEW: Per-thread output buffer - Enhanced redirect detection to use thread-specific output buffers, ensuring accurate session error detection in multi-target mode
• IMPROVE: Enhanced session error notifications - Session error emails now include both the session account (logged-in user or anonymous) and the target user that triggered the error, providing better context for debugging
• NEW: Added MULTI_TARGET_STAGGER, MULTI_TARGET_STAGGER_JITTER, and MULTI_TARGET_SERIALIZE_HTTP configuration options for fine-tuning multi-target behavior
• NEW: Added TARGET_USERNAMES configuration option to specify multiple targets in config file (CLI arguments take precedence)
• IMPROVE: Thread-safe logging with lock protection to prevent interleaved output when multiple targets write simultaneously
• IMPROVE: File save messages now include the username (e.g., "Story video saved for {user} to '{filename}'") for better clarity when monitoring multiple users
• IMPROVE: Enhanced error messages for Instagram challenge/shadow ban detection - when Instagram requires a challenge/re-login or temporarily shadow bans the IP, error messages now provide clear, informative explanations instead of cryptic KeyError 'data' messages
• IMPROVE: Follower/following count comparison - Enhanced display of reported vs actual follower/following counts with improved accuracy by refreshing profile data after fetching lists to ensure current reported counts are compared with actual fetched counts (thanks @tomballgithub)
• IMPROVE: Enhanced initialization progress messages - During script initialization, progress messages now show what's happening during profile loading, including loading profile from username, fetching reels count (when applicable), checking for stories (when applicable) and loading own profile (when logged in). This provides better visibility into the initialization process and helps with debugging account ban issues (thanks @tomballgithub)
• IMPROVE: Standardized formatting in print statements

Bug fixes:

• BUGFIX: Fixed redirect detection buffer that was using broken shared/local variable logic, now properly uses per-thread output tracking
• BUGFIX: Fixed follower/following count comparison logic - Removed inefficient helper functions that were fetching full lists just to get counts, simplified comparison function with proper type hints and fixed order of operations to ensure accurate reported vs actual count comparisons

Dependencies:

• NEW: Added tqdm dependency for progress bar functionality

Changes in 1.9.1 (18 Dec 2025)

Features and Improvements:

• IMPROVE: Enhanced CHECK_POSTS_IN_HOURS_RANGE logic: hour ranges now gate fetching updates (not just posts/reels), covering additional monitored activity (thanks @tomballgithub)
• NEW: Added HOURS_VERBOSE for debugging hour-based update gating (prints whether updates are fetched or skipped) (thanks @tomballgithub)
• IMPROVE: Refactored hour-range calculations: de-duplicate overlapping ranges, ignore invalid hours and prevent crashes on misconfiguration
• IMPROVE: Improved Be Human action probability when hour-range mode is enabled (scales to the configured active-hour window) (thanks @tomballgithub)
• IMPROVE: Added messaging for sleep time if HOURS_VERBOSE is enabled to give insight into when next check will be (thanks @tomballgithub)
• IMPROVE: Liveness check logic is now recomputed after config/env/CLI overrides are applied and after check-interval changes via signals
• IMPROVE: Improved Firefox session import handling (safer SQLite connection usage; clarified error message; consistent session path handling)
• IMPROVE: Enhanced sleep message output and refined hour range checks for updates

Bug fixes:

• BUGFIX: Fixed missing current-hour (cur_h) assignment that could break hour-range gating
• BUGFIX: Restored Python 3.9 compatibility in type hints (replaced datetime | None with Optional[datetime])

Changes in 1.8.1 (30 Nov 2025)

Features and Improvements:

• IMPROVE: Improved error handling for check intervals

Bug fixes:

• BUGFIX: Corrected bug in compare_images() function (thanks @jl-nr)

Changes in 1.8 (18 Jun 2025)

Features and Improvements:

• NEW: Added mobile-web JSON fallback to restore post details fetching in mode 1 (no session); reel details still require mode 2 (session login)
• IMPROVE: Added missing exception handling in several areas and included display of exception types for better debugging

Bug fixes:

• BUGFIX: Guarded has_public_story behind login check due to recent Instagram API anonymous session changes

Changes in 1.7 (13 Jun 2025)

Features and Improvements:

• NEW: Introduced new experimental Be Human mode that makes the tool behave more like a real user to reduce bot detection by performing random feed / profile / hashtag / followee actions. It is disabled by default, check the Human Mode for more info.
• NEW: Added new Jitter mode which allows to force every HTTP call made by Instaloader to go through a built-in jitter/back-off layer to look more human. It is disabled by default, check the Jitter Mode for more info.
• NEW: Added config options and flags to set desktop and mobile Instagram user agent strings. Check User Agent for more info.
• NEW: Ensured all Instagram requests now include the appropriate user agent, if not specified - they are randomly generated per session

Bug fixes:

• BUGFIX: Fixed config file generation to work reliably on Windows systems

Changes in 1.6.2 (22 May 2025)

Bug fixes:

• BUGFIX: Extended try block to suppress full stack trace
• BUGFIX: Corrected VERSION assignment syntax in source code

Changes in 1.6 (21 May 2025)

Features and Improvements:

• NEW: The tool can now be installed via pip: pip install instagram_monitor
• NEW: Added support for external config files, environment-based secrets and dotenv integration with auto-discovery
• NEW: Added full support for Instagram reels (not just video posts) and optimized post/reel fetching to reduce API calls
• NEW: Added --import-firefox-session to load session from Firefox cookies with detection of all profiles (replaces old script)
• IMPROVE: Improved detail extraction for posts and reels (via mobile API)
• NEW: Added notification for follow-request acceptance and for removed posts/reels
• NEW: Display access scope and session user info, including reels count
• IMPROVE: Enhanced session-login logic to auto‐load or create Instaloader sessions
• IMPROVE: Display whether the user can access all content of the monitored account
• IMPROVE: Enhanced startup summary to show loaded config, dotenv and empty profile pic template file paths
• IMPROVE: Auto detect and display availability of imgcat binary for profile picture preview
• IMPROVE: Simplified and renamed command-line arguments for improved usability
• NEW: Implemented SIGHUP handler for dynamic reload of secrets from dotenv files
• NEW: Added configuration option to control clearing the terminal screen at startup
• IMPROVE: Changed connectivity check to use Instagram API endpoint for better reliability
• IMPROVE: Added check for missing pip dependencies with install guidance
• IMPROVE: Allow disabling liveness check by setting interval to 0 (default changed to 12h)
• IMPROVE: Improved handling of log file creation
• IMPROVE: Refactored CSV file initialization and processing
• NEW: Added support for ~ path expansion across all file paths
• IMPROVE: Added validation for configured time zones
• IMPROVE: Refactored code structure to support packaging for PyPI
• IMPROVE: Enforced configuration option precedence: code defaults < config file < env vars < CLI flags
• IMPROVE: Made empty profile picture template path configurable
• IMPROVE: Only show profile picture template status if the file exists
• IMPROVE: Renamed Caption to Description in logs and email bodies
• IMPROVE: Email notifications now auto-disable if SMTP config is invalid
• IMPROVE: Minimum required Python version increased to 3.9
• IMPROVE: Removed short option for --send-test-email to avoid ambiguity

Bug fixes:

• BUGFIX: Fixed data key error, however due to Instagram changes, post/reel details can no longer be fetched in mode 1 (no session), though count differences are still reported
• BUGFIX: Fixed post location fetching after Instagram broke legacy endpoints
• BUGFIX: Corrected public vs. private story checks and iteration (#9)
• BUGFIX: Fixed rare issue with reporting changed profile pic even though timestamp is the same
• BUGFIX: Fixed issue where manually defined LOCAL_TIMEZONE wasn't applied correctly
• BUGFIX: Fixed imgcat command under Windows (use echo. & instead of echo ;)

Changes in 1.5 (03 Nov 2024)

Features and Improvements:

• NEW: Possibility to skip getting posts details (new -w / --skip_getting_posts_details parameter)
• IMPROVE: Print message changed when empty followers list is returned
• IMPROVE: Added message about fetching user's latest post/reel (as it might take a while)

Bug fixes:

• BUGFIX: Fixed bug with saving removed followers/followings to CSV file when empty list is returned and count is > 0
• BUGFIX: Fixed wrong CSV entry timestamp in case posts number decreases

Changes in 1.4 (02 Aug 2024)

Features and Improvements:

• NEW: Detection when user changes profile visibility from public to private and vice-versa; the code already supported both private and public profiles, however it did not inform the user when the profile visibility has changed; now the tool will notify about it in the console and also via email notifications (-s) and CSV file records (-b)
• IMPROVE: Added info about used mode of the tool in the main screen, so it is easier to correlate it with the description in the README

Bug fixes:

• BUGFIX: Indentation fixes in the code

Changes in 1.3 (14 Jun 2024)

Features and Improvements:

• NEW: Added new parameter (**-z|*8 / --send_test_email_notification) which allows to send test email notification to verify SMTP settings defined in the script
• IMPROVE: Checking if correct version of Python (>=3.8) is installed
• IMPROVE: Possibility to define email sending timeout (default set to 15 secs)

Bug fixes:

• BUGFIX: Fixed "SyntaxError: f-string: unmatched (" issue in older Python versions
• BUGFIX: Fixed "SyntaxError: f-string expression part cannot include a backslash" issue in older Python versions

Changes in 1.2 (07 Jun 2024)

Features and Improvements:

• IMPROVE: pyright complained the code is too complex to analyze, so it has been simplified little bit (so it does not complain anymore)
• IMPROVE: Changed email notifications string in SIGUSR1 signal handler

Bug fixes:

• BUGFIX: Fixed nasty bug terminating the script in case of issues while processing story items (yes, copy & paste bug ;-))

Changes in 1.1 (03 Jun 2024)

Features and Improvements:

• NEW: Support for detecting multiple stories (if session login is used)
• NEW: Fully anonymous download of user's story images & videos (thumbnail image will be also attached in email notifications and displayed in the terminal if imgcat is installed); yes, user won't know you watched their stories 😉
• NEW: Download of user's post images & videos (thumbnail image will be also attached in email notifications and displayed in the terminal if imgcat is installed)
• NEW: Detection of changed profile pictures; since Instagram user's profile picture URL seems to change from time to time, the tool detects changed profile picture by doing binary comparison of saved jpg files; initially it saves the profile pic to instagram_{user}_profile_pic.jpg file after the tool is started; then during every check the new picture is fetched and the tool does binary comparison if it has changed or not; in case of changes the old profile picture is moved to instagram_{user}_profile_pic_old.jpg file and the new one is saved to instagram_{user}_profile_pic.jpg and also to file named instagram_{user}_profile_pic_YYmmdd_HHMM.jpg (so we can have history of all profile pictures); in order to control the feature there is a new DETECT_CHANGED_PROFILE_PIC variable set to True by default; the feature can be disabled by setting it to False or by enabling -k / --do_not_detect_changed_profile_pic parameter
• NEW: Detection of empty profile pictures; Instagram does not signal the fact of empty user's profile image in their API, that's why we can detect it by using empty profile image template (which seems to be the same on binary level for all users); to use this feature put instagram_profile_pic_empty.jpg file in the dir from which you run the script; this way the tool will be able to detect when user does not have profile image set; it is not mandatory, but highly recommended as otherwise the tool will treat empty profile pic as regular one, so for example user's removal of profile picture will be detected as changed profile picture
• NEW: Attaching changed profile pics and stories/posts images directly in email notifications (when -s parameter is used)
• NEW: Feature allowing to display the profile picture and stories/posts images right in your terminal (if you have imgcat installed); put path to your imgcat binary in IMGCAT_PATH variable (or leave it empty to disable this functionality)
• IMPROVE: Improvements for running the code in Python under Windows
• NEW: Automatic detection of local timezone if you set LOCAL_TIMEZONE variable to 'Auto' (it is default now); requires tzlocal pip module
• NEW: Support for honoring last-modified timestamp for saved profile pics (it turned out it reflects timestamp when the picture has been actually added by the user)
• IMPROVE: Information about time zone and posts checking hours is displayed in the start screen now
• NEW: Fetching of post's location and comments + likes list is back (however needs to be enabled via -t parameter as it highly increases the risk that Instagram will mark the account as an automated tool)
• NEW: Added new parameter -r / --skip_getting_story_details to skip getting detailed info about stories and its images/videos, even if session login is used; you will still get generic information about new stories in such case
• NEW: Added new parameter -t / --get_more_post_details to get more detailed info about new posts like its location and comments + likes list, only possible if session login is used; if not enabled you will still get generic information about new posts; it is disabled by default as for some unknown reasons it highly increases the risk of the account being flagged as an automated tool
• NEW: Added new parameter -k / --do_not_detect_changed_profile_pic which allows to disable detection of changed user's profile picture
• IMPROVE: Email sending function send_email() has been rewritten to detect invalid SMTP settings + possibility to attach images
• IMPROVE: Strings converted to f-strings for better code visibility
• IMPROVE: Rewritten get_date_from_ts(), get_short_date_from_ts(), get_hour_min_from_ts() and get_range_of_dates_from_tss() functions to automatically detect it time object is timestamp (int/float) or datetime
• IMPROVE: Better checking for wrong command line arguments
• IMPROVE: Help screen reorganization
• IMPROVE: pep8 style convention corrections

Bug fixes:

• BUGFIX: Improved exception handling while processing JSON files
• BUGFIX: Escaping of potentially dangerous variables in HTML email templates
• BUGFIX: Fix for saving empty followers/followings list to JSON file when the tool is started and Instagram API returns empty list

Changes in 1.0 (25 Apr 2024)

Features and Improvements:

• NEW: Support for Instagram users having no posts yet
• NEW: Support for handling private profiles
• IMPROVE: Improvements in monitoring Instagram user activity without session

Bug fixes:

• BUGFIX: Disabled fetching location, list of likes and comments for posts due to errors after recent Instagram changes (HTTP Error 400)