Release of Version 4.12

Fix GitHub Actions Node.js deprecation warnings.

Use actions/setup-python cache where appropriate.

.github/workflows/documentation.yml

@@ -8,13 +8,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "Checkout Instaloader Repository"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0  # needed for building docs
       - name: "Setup Python"
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: 3.12
+          cache: 'pipenv'
       - name: "Install Dependencies"
         run: |
           python -m pip install pipenv==2023.12.1
@@ -23,7 +24,7 @@ jobs:
         run: pipenv --python `python --version | grep -Eo '3\.[0-9]+'` run make -C docs html SPHINXOPTS="-W -n"
       - name: "Deploy Documentation"
         if: github.event_name == 'push' && github.ref == 'refs/heads/master'
-        uses: JamesIves/github-pages-deploy-action@v4.2.5
+        uses: JamesIves/github-pages-deploy-action@v4
         with:
           branch: master
           repository-name: instaloader/instaloader.github.io

.github/workflows/lint.yml

@@ -12,11 +12,12 @@ jobs:
         python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
       - name: Checkout Instaloader Repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Setup Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: 'pipenv'
       - name: Install Dependencies
         run: |
           python -m pip install pipenv==2023.12.1

.github/workflows/packages.yml

@@ -11,16 +11,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "Checkout Repository"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "Setup Python"
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: 3.12
       - name: "Get the tagged version"
         id: get_version
         env:
           GITHUB_REF: ${{ github.ref }}
-        run: echo ::set-output name=VERSION::${GITHUB_REF/refs\/tags\/v/}
+        run: echo "VERSION=${GITHUB_REF/refs\/tags\/v/}" >> $GITHUB_OUTPUT
         shell: bash
       - name: "Install Dependencies"
         run: python -m pip install setuptools

.github/workflows/stale.yml

@@ -2,7 +2,7 @@ name: Mark stale issues and pull requests
 
 on:
   schedule:
-  - cron: "10 14 * * *"
+  - cron: "55 7 * * *"
 
 jobs:
   stale:
@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     
     steps:
-    - uses: actions/stale@v3
+    - uses: actions/stale@v9
       with:
         repo-token: ${{ secrets.GITHUB_TOKEN }}
         only-labels: 'question'
@@ -21,14 +21,14 @@ jobs:
         days-before-stale: 21
         days-before-close: -1
         remove-stale-when-updated: false
-    - uses: actions/stale@v1
+    - uses: actions/stale@v9
       with:
         repo-token: ${{ secrets.GITHUB_TOKEN }}
         stale-issue-message: 'There has been no activity on this issue for an extended period of time. This issue will be closed after further 14 days of inactivity.'
         stale-pr-message: 'There has been no activity on this Pull Request for an extended period of time. This Pull Request will be closed after further 14 days of inactivity.'
         stale-issue-label: 'stale'
         stale-pr-label: 'stale'
-        exempt-issue-label: 'leave open'
-        exempt-pr-label: 'leave open'
+        exempt-issue-labels: 'leave open'
+        exempt-pr-labels: 'leave open'
         days-before-stale: 189
         days-before-close: 14

.github/workflows/windows_exe.yml

@@ -8,17 +8,18 @@ jobs:
     runs-on: windows-latest
     steps:
       - name: Checkout Instaloader repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Setup Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+          cache: 'pipenv'
           architecture: x64
       - name: Get the tagged version
         id: get_version
         env:
           GITHUB_REF: ${{ github.ref }}
-        run: echo ::set-output name=VERSION::${GITHUB_REF/refs\/tags\/v/}
+        run: echo "VERSION=${GITHUB_REF/refs\/tags\/v/}" >> $GITHUB_OUTPUT
         shell: bash
       - name: Run custom python script for EXE creation
         env:

docs/basic-usage.rst

@@ -75,7 +75,7 @@ What to Download
 Instaloader supports the following targets:
 
 - ``profile``
-   Public profile, or private profile with :option:`--login`.
+   Public profile, or private profile with :ref:`login<login>`.
 
    If an already-downloaded profile has been renamed, Instaloader automatically
    finds it by its unique ID and renames the folder accordingly.
@@ -102,23 +102,23 @@ Instaloader supports the following targets:
    Posts tagged with a given location; the location ID is the numerical ID
    Instagram labels a location with (e.g.
    \https://www.instagram.com/explore/locations/**362629379**/plymouth-naval-memorial/).
-   Requires :option:`--login`.
+   Requires :ref:`login<login>`.
 
    .. versionadded:: 4.2
 
 - ``:stories``
    The currently-visible **stories** of your followees (requires
-   :option:`--login`).
+   :ref:`login<login>`).
 
 - ``:feed``
-   Your **feed** (requires :option:`--login`).
+   Your **feed** (requires :ref:`login<login>`).
 
 - ``:saved``
-   Posts which are marked as **saved** (requires :option:`--login`).
+   Posts which are marked as **saved** (requires :ref:`login<login>`).
 
 - ``@profile``
    All profiles that are followed by ``profile``, i.e. the *followees* of
-   ``profile`` (requires :option:`--login`).
+   ``profile`` (requires :ref:`login<login>`).
 
 - ``-post``
    Replace **post** with the post's shortcode to download single post. Must be preceded by ``--`` in
@@ -140,7 +140,7 @@ downloads the pictures and videos and their captions. You can specify
 
 - :option:`--geotags`
    **download geotags** of each post and save them as
-   Google Maps link (requires :option:`--login`),
+   Google Maps link (requires :ref:`login<login>`),
 
 For a reference of all supported command line options, see
 :ref:`command-line-options`.
@@ -255,7 +255,7 @@ Id est, the following attributes can be used with both
 As :option:`--post-filter`, the following attributes can be used additionally:
 
 - :attr:`~Post.viewer_has_liked` (bool)
-   Whether user (with :option:`--login`) has liked given post. To download the
+   Whether user (with :ref:`login<login>`) has liked given post. To download the
    pictures from your feed that you have liked::
 
       instaloader --login=your_username --post-filter=viewer_has_liked :feed
@@ -307,13 +307,47 @@ the post's caption::
 
    instaloader --post-metadata-txt="{likes} likes." <target>
 
-Note that with this feature, it is possible to easily and fastly extract
+Note that with this feature, it is possible to easily and quickly extract
 additional metadata of already-downloaded posts, by reimporting their JSON
 files. Say, you now also want to export the number of comments the Posts had
 when they were downloaded::
 
    instaloader --post-metadata-txt="{likes} likes, {comments} comments." <target>/*.json.xz
 
+.. _exit_codes:
+
+Exit codes
+^^^^^^^^^^
+
+Different exit codes are used to indicate different kinds of error:
+
+0
+  No error, all downloads were successful.
+
+1
+  A non-fatal error happened. One or more posts, or even one or more
+  profiles could not be downloaded, but execution was not stopped. The
+  errors are repeated at the end of the log for easy access.
+
+2
+  Command-line error. An unrecognized option was passed, or an invalid
+  combination of options, for example. No interaction with Instagram
+  was made.
+
+3
+  Login error. It was not possible to login. Downloads were not
+  attempted.
+
+4
+  Fatal download error. Downloads were interrupted and no further
+  attempts were made. Happens when a response with one of the status
+  codes in the :option:`--abort-on` option were passed, or when
+  Instagram logs the user out during downloads.
+
+5
+  Interrupted by the user. Happens when the user presses Control-C or
+  sends SIGINT to the process.
+
 .. _instaloader-as-cronjob:
 
 Instaloader as Cronjob

docs/cli-options.rst

@@ -26,7 +26,7 @@ Targets
 ^^^^^^^
 
 Specify a list of targets. For each of these, Instaloader creates a folder and
-stores all posts along with the pictures's captions there.
+stores all posts along with the pictures' captions there.
 
 .. include:: basic-usage.rst
    :start-after: targets-start
@@ -61,13 +61,13 @@ What to Download of each Post
 
    Download geotags when available. Geotags are stored as a text file with
    the location's name and a Google Maps link. This requires an additional
-   request to the Instagram server for each picture. Requires :option:`--login`.
+   request to the Instagram server for each picture. Requires :ref:`login<login>`.
 
 .. option:: --comments, -C
 
    Download and update comments for each post. This requires an additional
    request to the Instagram server for each post, which is why it is disabled by
-   default.
+   default. Requires :ref:`login<login>`.
 
 .. option:: --no-captions
 
@@ -116,12 +116,12 @@ What to Download of each Profile
 .. option:: --stories, -s
 
    Also download stories of each profile that is downloaded. Requires
-   :option:`--login`.
+   :ref:`login<login>`.
 
 .. option:: --highlights
 
    Also download highlights of each profile that is downloaded. Requires
-   :option:`--login`.
+   :ref:`login<login>`.
 
    .. versionadded:: 4.1
 
@@ -183,6 +183,7 @@ Which Posts to Download
    Do not attempt to download more than COUNT posts.  Applies to
    ``#hashtag``, ``%location_id``, ``:feed``, and ``:saved``.
 
+.. _login:
 
 Login (Download Private Profiles)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -192,6 +193,9 @@ profiles. To login, pass the :option:`--login` option. Your session cookie (not
 password!) will be saved to a local file to be reused next time you want
 Instaloader to login.
 
+Instead of :option:`--login`, it is possible to use
+:option:`--load-cookies` to import a session from a browser.
+
 .. option:: --login YOUR-USERNAME, -l YOUR-USERNAME
 
    Login name (profile name) for your Instagram account.
@@ -202,10 +206,10 @@ Instaloader to login.
    This feature requires the browser_cookie3 library.
    Compatible with :option:`--cookiefile` if you want to load cookies from browser profiles.
    Incompatible with :option:`--login` due to potential username mismatch between user input and browser login.
-   Supported browsers: Chrome, Firefox, Edge, Opera, Safari, Brave.
+   Supported browsers: Brave, Chrome, Chromium, Edge, Firefox, LibreWolf, Opera, Opera_GX, Safari and Vivaldi.
 
-   After loading the cookies run the :option:`--login` option as it is required to download high quality media
-   and to make full use of Instaloader's features.
+   In subsequent runs, you can just use :option:`--login` to reuse the
+   same session, which is saved by Instaloader.
 
    .. versionadded:: 4.11
 

docs/module/exceptions.rst

@@ -27,16 +27,26 @@ Exceptions
 
 .. autoexception:: LoginRequiredException
 
+.. autoexception:: LoginException
+
+   .. versionadded:: 4.12
+
 .. autoexception:: TwoFactorAuthRequiredException
 
    .. versionadded:: 4.2
 
+   .. versionchanged:: 4.12
+      Inherits LoginException
+
 .. autoexception:: InvalidArgumentException
 
 .. autoexception:: BadResponseException
 
 .. autoexception:: BadCredentialsException
 
+   .. versionchanged:: 4.12
+      Inherits LoginException
+
 .. autoexception:: PostChangedException
 
 .. autoexception:: QueryReturnedNotFoundException

docs/troubleshooting.rst

@@ -33,7 +33,7 @@ happen under normal conditions, consider adjusting the
 There have been observations that services, that in their nature offer
 promiscuous IP addresses, such as cloud, VPN and public proxy services, might be
 subject to significantly stricter limits for anonymous access. However,
-logged-in accesses (see :option:`--login`) do not seem to be affected.
+:ref:`logged-in accesses<login>` do not seem to be affected.
 
 Instaloader allows to adjust the rate controlling behavior by overriding
 :class:`instaloader.RateController`.

instaloader/__init__.py

@@ -1,7 +1,7 @@
 """Download pictures (or videos) along with their captions and other metadata from Instagram."""
 
 
-__version__ = '4.11'
+__version__ = '4.12'
 
 
 try:

instaloader/__main__.py

@@ -5,12 +5,12 @@ import datetime
 import os
 import re
 import sys
-import textwrap
 from argparse import ArgumentParser, ArgumentTypeError, SUPPRESS
+from enum import IntEnum
 from typing import List, Optional
 
 from . import (AbortDownloadException, BadCredentialsException, Instaloader, InstaloaderException,
-               InvalidArgumentException, Post, Profile, ProfileNotExistsException, StoryItem,
+               InvalidArgumentException, LoginException, Post, Profile, ProfileNotExistsException, StoryItem,
                TwoFactorAuthRequiredException, __version__, load_structure_from_file)
 from .instaloader import (get_default_session_filename, get_default_stamps_filename)
 from .instaloadercontext import default_user_agent
@@ -22,6 +22,15 @@ except ImportError:
     bc3_library = False
 
 
+class ExitCode(IntEnum):
+    SUCCESS = 0
+    NON_FATAL_ERROR = 1
+    INIT_FAILURE = 2
+    LOGIN_FAILURE = 3
+    DOWNLOAD_ABORTED = 4
+    USER_ABORTED = 5
+    UNEXPECTED_ERROR = 99
+
 def usage_string():
     # NOTE: duplicated in README.rst and docs/index.rst
     argv0 = os.path.basename(sys.argv[0])
@@ -75,18 +84,22 @@ def filterstr_to_filterfunc(filter_str: str, item_type: type):
 
 def get_cookies_from_instagram(domain, browser, cookie_file='', cookie_name=''):
     supported_browsers = {
-        "chrome": browser_cookie3.chrome,
-        "firefox": browser_cookie3.firefox,
-        "edge": browser_cookie3.edge,
         "brave": browser_cookie3.brave,
+        "chrome": browser_cookie3.chrome,
+        "chromium": browser_cookie3.chromium,
+        "edge": browser_cookie3.edge,
+        "firefox": browser_cookie3.firefox,
+        "librewolf": browser_cookie3.librewolf,
         "opera": browser_cookie3.opera,
-        "safari": browser_cookie3.safari
+        "opera_gx": browser_cookie3.opera_gx,
+        "safari": browser_cookie3.safari,
+        "vivaldi": browser_cookie3.vivaldi,
     }
 
     if browser not in supported_browsers:
-        print("Loading cookies from the specified browser failed")
-        print("Supported browsers are Chrome, Firefox, Edge, Brave, Opera and Safari")
-        return {}
+        raise InvalidArgumentException("Loading cookies from the specified browser failed\n"
+                                       "Supported browsers are Brave, Chrome, Chromium, Edge, Firefox, LibreWolf, "
+                                       "Opera, Opera_GX, Safari and Vivaldi")
 
     cookies = {}
     browser_cookies = list(supported_browsers[browser](cookie_file=cookie_file))
@@ -98,7 +111,8 @@ def get_cookies_from_instagram(domain, browser, cookie_file='', cookie_name=''):
     if cookies:
         print(f"Cookies loaded successfully from {browser}")
     else:
-        print(f"No cookies found for Instagram in {browser}, Are you logged in succesfully in {browser}?")
+        raise LoginException(f"No cookies found for Instagram in {browser}, "
+                             f"Are you logged in succesfully in {browser}?")
 
     if cookie_name:
         return cookies.get(cookie_name, {})
@@ -112,12 +126,10 @@ def import_session(browser, instaloader, cookiefile):
         instaloader.context.update_cookies(cookie)
         username = instaloader.test_login()
         if not username:
-            raise SystemExit(f"Not logged in. Are you logged in successfully in {browser}?")
+            raise LoginException(f"Not logged in. Are you logged in successfully in {browser}?")
         instaloader.context.username = username
         print(f"{username} has been successfully logged in.")
-        next_step_text = (f"Next: Run instaloader --login={username} as it is required to download high quality media "
-                          "and to make full use of instaloader's features.")
-        print(textwrap.fill(next_step_text))
+        print(f"Next time use --login={username} to reuse the same session.")
 
 
 def _main(instaloader: Instaloader, targetlist: List[str],
@@ -133,7 +145,7 @@ def _main(instaloader: Instaloader, targetlist: List[str],
           max_count: Optional[int] = None, post_filter_str: Optional[str] = None,
           storyitem_filter_str: Optional[str] = None,
           browser: Optional[str] = None,
-          cookiefile: Optional[str] = None) -> None:
+          cookiefile: Optional[str] = None) -> ExitCode:
     """Download set of profiles, hashtags etc. and handle logging in and session files if desired."""
     # Parse and generate filter function
     post_filter = None
@@ -152,7 +164,7 @@ def _main(instaloader: Instaloader, targetlist: List[str],
     if browser and bc3_library:
         import_session(browser.lower(), instaloader, cookiefile)
     elif browser and not bc3_library:
-        raise SystemExit("browser_cookie3 library is needed to load cookies from browsers")
+        raise InvalidArgumentException("browser_cookie3 library is needed to load cookies from browsers")
     # Login, if desired
     if username is not None:
         if not re.match(r"^[A-Za-z0-9._]+$", username):
@@ -181,14 +193,19 @@ def _main(instaloader: Instaloader, targetlist: List[str],
                             print(err, file=sys.stderr)
                             pass
             else:
-                instaloader.interactive_login(username)
+                try:
+                    instaloader.interactive_login(username)
+                except KeyboardInterrupt:
+                    print("\nInterrupted by user.", file=sys.stderr)
+                    return ExitCode.USER_ABORTED
         instaloader.context.log("Logged in as %s." % username)
     # since 4.2.9 login is required for geotags
     if instaloader.download_geotags and not instaloader.context.is_logged_in:
-        instaloader.context.error("Warning: Use --login to download geotags of posts.")
+        instaloader.context.error("Warning: Login is required to download geotags of posts.")
     # Try block for KeyboardInterrupt (save session on ^C)
     profiles = set()
     anonymous_retry_profiles = set()
+    exit_code = ExitCode.SUCCESS
     try:
         # Generate set of profiles, already downloading non-profile targets
         for target in targetlist:
@@ -279,7 +296,7 @@ def _main(instaloader: Instaloader, targetlist: List[str],
                                                                          ' '.join([p.username for p in profiles])))
         if instaloader.context.iphone_support and profiles and (download_profile_pic or download_posts) and \
            not instaloader.context.is_logged_in:
-            instaloader.context.log("Hint: Use --login to download higher-quality versions of pictures.")
+            instaloader.context.log("Hint: Login to download higher-quality versions of pictures.")
         instaloader.download_profiles(profiles,
                                       download_profile_pic, download_posts, download_tagged, download_igtv,
                                       download_highlights, download_stories,
@@ -294,8 +311,10 @@ def _main(instaloader: Instaloader, targetlist: List[str],
                                                    latest_stamps=latest_stamps)
     except KeyboardInterrupt:
         print("\nInterrupted by user.", file=sys.stderr)
+        exit_code = ExitCode.USER_ABORTED
     except AbortDownloadException as exc:
         print("\nDownload aborted: {}.".format(exc), file=sys.stderr)
+        exit_code = ExitCode.DOWNLOAD_ABORTED
     # Save session if it is useful
     if instaloader.context.is_logged_in:
         instaloader.save_session_to_file(sessionfile)
@@ -307,6 +326,8 @@ def _main(instaloader: Instaloader, targetlist: List[str],
         else:
             # Instaloader did not do anything
             instaloader.context.log("usage:" + usage_string())
+            exit_code = ExitCode.INIT_FAILURE
+    return exit_code
 
 
 def main():
@@ -322,17 +343,17 @@ def main():
                            help="Download profile. If an already-downloaded profile has been renamed, Instaloader "
                                 "automatically finds it by its unique ID and renames the folder likewise.")
     g_targets.add_argument('_at_profile', nargs='*', metavar="@profile",
-                           help="Download all followees of profile. Requires --login. "
+                           help="Download all followees of profile. Requires login. "
                                 "Consider using :feed rather than @yourself.")
     g_targets.add_argument('_hashtag', nargs='*', metavar='"#hashtag"', help="Download #hashtag.")
     g_targets.add_argument('_location', nargs='*', metavar='%location_id',
-                           help="Download %%location_id. Requires --login.")
+                           help="Download %%location_id. Requires login.")
     g_targets.add_argument('_feed', nargs='*', metavar=":feed",
-                           help="Download pictures from your feed. Requires --login.")
+                           help="Download pictures from your feed. Requires login.")
     g_targets.add_argument('_stories', nargs='*', metavar=":stories",
-                           help="Download the stories of your followees. Requires --login.")
+                           help="Download the stories of your followees. Requires login.")
     g_targets.add_argument('_saved', nargs='*', metavar=":saved",
-                           help="Download the posts that you marked as saved. Requires --login.")
+                           help="Download the posts that you marked as saved. Requires login.")
     g_targets.add_argument('_singlepost', nargs='*', metavar="-- -shortcode",
                            help="Download the post with the given shortcode")
     g_targets.add_argument('_json', nargs='*', metavar="filename.json[.xz]",
@@ -363,11 +384,11 @@ def main():
                         help='Download geotags when available. Geotags are stored as a '
                              'text file with the location\'s name and a Google Maps link. '
                              'This requires an additional request to the Instagram '
-                             'server for each picture. Requires --login.')
+                             'server for each picture. Requires login.')
     g_post.add_argument('-C', '--comments', action='store_true',
                         help='Download and update comments for each post. '
                              'This requires an additional request to the Instagram '
-                             'server for each post, which is why it is disabled by default.')
+                             'server for each post, which is why it is disabled by default. Requires login.')
     g_post.add_argument('--no-captions', action='store_true',
                         help='Do not create txt files.')
     g_post.add_argument('--post-metadata-txt', action='append',
@@ -381,11 +402,11 @@ def main():
     g_post.add_argument('--no-compress-json', action='store_true',
                         help='Do not xz compress JSON files, rather create pretty formatted JSONs.')
     g_prof.add_argument('-s', '--stories', action='store_true',
-                        help='Also download stories of each profile that is downloaded. Requires --login.')
+                        help='Also download stories of each profile that is downloaded. Requires login.')
     g_prof.add_argument('--stories-only', action='store_true',
                         help=SUPPRESS)
     g_prof.add_argument('--highlights', action='store_true',
-                        help='Also download highlights of each profile that is downloaded. Requires --login.')
+                        help='Also download highlights of each profile that is downloaded. Requires login.')
     g_prof.add_argument('--tagged', action='store_true',
                         help='Also download posts where each profile is tagged.')
     g_prof.add_argument('--igtv', action='store_true',
@@ -417,7 +438,8 @@ def main():
                                         'Instaloader can login to Instagram. This allows downloading private profiles. '
                                         'To login, pass the --login option. Your session cookie (not your password!) '
                                         'will be saved to a local file to be reused next time you want Instaloader '
-                                        'to login.')
+                                        'to login. Instead of --login, the --load-cookies option can be used to '
+                                        'import a session from a browser.')
     g_login.add_argument('-l', '--login', metavar='YOUR-USERNAME',
                          help='Login name (profile name) for your Instagram account.')
     g_login.add_argument('-b', '--load-cookies', metavar='BROWSER-NAME',
@@ -484,15 +506,15 @@ def main():
 
     args = parser.parse_args()
     try:
-        if args.login is None and (args.stories or args.stories_only):
-            print("--login=USERNAME required to download stories.", file=sys.stderr)
+        if (args.login is None and args.load_cookies is None) and (args.stories or args.stories_only):
+            print("Login is required to download stories.", file=sys.stderr)
             args.stories = False
             if args.stories_only:
-                raise SystemExit(1)
+                raise InvalidArgumentException()
 
         if ':feed-all' in args.profile or ':feed-liked' in args.profile:
-            raise SystemExit(":feed-all and :feed-liked were removed. Use :feed as target and "
-                             "eventually --post-filter=viewer_has_liked.")
+            raise InvalidArgumentException(":feed-all and :feed-liked were removed. Use :feed as target and "
+                                           "eventually --post-filter=viewer_has_liked.")
 
         post_metadata_txt_pattern = '\n'.join(args.post_metadata_txt) if args.post_metadata_txt else None
         storyitem_metadata_txt_pattern = '\n'.join(args.storyitem_metadata_txt) if args.storyitem_metadata_txt else None
@@ -502,18 +524,18 @@ def main():
                 post_metadata_txt_pattern = ''
                 storyitem_metadata_txt_pattern = ''
             else:
-                raise SystemExit("--no-captions and --post-metadata-txt or --storyitem-metadata-txt given; "
-                                 "That contradicts.")
+                raise InvalidArgumentException("--no-captions and --post-metadata-txt or --storyitem-metadata-txt "
+                                               "given; That contradicts.")
 
         if args.no_resume and args.resume_prefix:
-            raise SystemExit("--no-resume and --resume-prefix given; That contradicts.")
+            raise InvalidArgumentException("--no-resume and --resume-prefix given; That contradicts.")
         resume_prefix = (args.resume_prefix if args.resume_prefix else 'iterator') if not args.no_resume else None
 
         if args.no_pictures and args.fast_update:
-            raise SystemExit('--no-pictures and --fast-update cannot be used together.')
+            raise InvalidArgumentException('--no-pictures and --fast-update cannot be used together.')
 
         if args.login and args.load_cookies:
-            raise SystemExit('--load-cookies and --login cannot be used together.')
+            raise InvalidArgumentException('--load-cookies and --login cannot be used together.')
 
         # Determine what to download
         download_profile_pic = not args.no_profile_pic or args.profile_pic_only
@@ -538,27 +560,37 @@ def main():
                              iphone_support=not args.no_iphone,
                              title_pattern=args.title_pattern,
                              sanitize_paths=args.sanitize_paths)
-        _main(loader,
-              args.profile,
-              username=args.login.lower() if args.login is not None else None,
-              password=args.password,
-              sessionfile=args.sessionfile,
-              download_profile_pic=download_profile_pic,
-              download_posts=download_posts,
-              download_stories=download_stories,
-              download_highlights=args.highlights,
-              download_tagged=args.tagged,
-              download_igtv=args.igtv,
-              fast_update=args.fast_update,
-              latest_stamps_file=args.latest_stamps,
-              max_count=int(args.count) if args.count is not None else None,
-              post_filter_str=args.post_filter,
-              storyitem_filter_str=args.storyitem_filter,
-              browser=args.load_cookies,
-              cookiefile=args.cookiefile)
+        exit_code = _main(loader,
+                          args.profile,
+                          username=args.login.lower() if args.login is not None else None,
+                          password=args.password,
+                          sessionfile=args.sessionfile,
+                          download_profile_pic=download_profile_pic,
+                          download_posts=download_posts,
+                          download_stories=download_stories,
+                          download_highlights=args.highlights,
+                          download_tagged=args.tagged,
+                          download_igtv=args.igtv,
+                          fast_update=args.fast_update,
+                          latest_stamps_file=args.latest_stamps,
+                          max_count=int(args.count) if args.count is not None else None,
+                          post_filter_str=args.post_filter,
+                          storyitem_filter_str=args.storyitem_filter,
+                          browser=args.load_cookies,
+                          cookiefile=args.cookiefile)
         loader.close()
+        if loader.has_stored_errors:
+            exit_code = ExitCode.NON_FATAL_ERROR
+    except InvalidArgumentException as err:
+        print(err, file=sys.stderr)
+        exit_code = ExitCode.INIT_FAILURE
+    except LoginException as err:
+        print(err, file=sys.stderr)
+        exit_code = ExitCode.LOGIN_FAILURE
     except InstaloaderException as err:
-        raise SystemExit("Fatal error: %s" % err) from err
+        print("Fatal error: %s" % err)
+        exit_code = ExitCode.UNEXPECTED_ERROR
+    sys.exit(exit_code)
 
 
 if __name__ == "__main__":

instaloader/exceptions.py

@@ -33,7 +33,11 @@ class LoginRequiredException(InstaloaderException):
     pass
 
 
-class TwoFactorAuthRequiredException(InstaloaderException):
+class LoginException(InstaloaderException):
+    pass
+
+
+class TwoFactorAuthRequiredException(LoginException):
     pass
 
 
@@ -45,7 +49,7 @@ class BadResponseException(InstaloaderException):
     pass
 
 
-class BadCredentialsException(InstaloaderException):
+class BadCredentialsException(LoginException):
     pass
 
 

instaloader/instaloader.py

@@ -77,7 +77,7 @@ def _requires_login(func: Callable) -> Callable:
     @wraps(func)
     def call(instaloader, *args, **kwargs):
         if not instaloader.context.is_logged_in:
-            raise LoginRequiredException("--login=USERNAME required.")
+            raise LoginRequiredException("Login required.")
         return func(instaloader, *args, **kwargs)
     return call
 
@@ -643,11 +643,16 @@ class Instaloader:
     def login(self, user: str, passwd: str) -> None:
         """Log in to instagram with given username and password and internally store session object.
 
-        :raises InvalidArgumentException: If the provided username does not exist.
         :raises BadCredentialsException: If the provided password is wrong.
-        :raises ConnectionException: If connection to Instagram failed.
         :raises TwoFactorAuthRequiredException: First step of 2FA login done, now call
-           :meth:`Instaloader.two_factor_login`."""
+           :meth:`Instaloader.two_factor_login`.
+        :raises LoginException: An error happened during login (for example, an invalid response was received).
+           Or if the provided username does not exist.
+
+        .. versionchanged:: 4.12
+           Raises LoginException instead of ConnectionException when an error happens.
+           Raises LoginException instead of InvalidArgumentException when the username does not exist.
+        """
         self.context.login(user, passwd)
 
     def two_factor_login(self, two_factor_code) -> None:
@@ -1460,7 +1465,7 @@ class Instaloader:
                 if tagged or igtv or highlights or posts:
                     if (not self.context.is_logged_in and
                             profile.is_private):
-                        raise LoginRequiredException("--login=USERNAME required.")
+                        raise LoginRequiredException("Login required.")
                     if (self.context.username != profile.username and
                             profile.is_private and
                             not profile.followed_by_viewer):
@@ -1582,11 +1587,16 @@ class Instaloader:
     def interactive_login(self, username: str) -> None:
         """Logs in and internally stores session, asking user for password interactively.
 
-        :raises LoginRequiredException: when in quiet mode.
-        :raises InvalidArgumentException: If the provided username does not exist.
-        :raises ConnectionException: If connection to Instagram failed."""
+        :raises InvalidArgumentException: when in quiet mode.
+        :raises LoginException: If the provided username does not exist.
+        :raises ConnectionException: If connection to Instagram failed.
+
+        .. versionchanged:: 4.12
+           Raises InvalidArgumentException instead of LoginRequiredException when in quiet mode.
+           Raises LoginException instead of InvalidArgumentException when the username does not exist.
+        """
         if self.context.quiet:
-            raise LoginRequiredException("Quiet mode requires given password or valid session file.")
+            raise InvalidArgumentException("Quiet mode requires given password or valid session file.")
         try:
             password = None
             while password is None:
@@ -1605,3 +1615,10 @@ class Instaloader:
                 except BadCredentialsException as err:
                     print(err, file=sys.stderr)
                     pass
+
+    @property
+    def has_stored_errors(self) -> bool:
+        """Returns whether any error has been reported and stored to be repeated at program termination.
+
+        .. versionadded: 4.12"""
+        return self.context.has_stored_errors

instaloader/instaloadercontext.py

@@ -9,7 +9,7 @@ import textwrap
 import time
 import urllib.parse
 import uuid
-from contextlib import contextmanager
+from contextlib import contextmanager, suppress
 from datetime import datetime, timedelta
 from functools import partial
 from typing import Any, Callable, Dict, Iterator, List, Optional, Union
@@ -151,6 +151,13 @@ class InstaloaderContext:
         if repeat_at_end:
             self.error_log.append(msg)
 
+    @property
+    def has_stored_errors(self) -> bool:
+        """Returns whether any error has been reported and stored to be repeated at program termination.
+
+        .. versionadded: 4.12"""
+        return bool(self.error_log)
+
     def close(self):
         """Print error log and close session"""
         if self.error_log and not self.quiet:
@@ -236,17 +243,26 @@ class InstaloaderContext:
 
     def test_login(self) -> Optional[str]:
         """Not meant to be used directly, use :meth:`Instaloader.test_login`."""
-        data = self.graphql_query("d6f4427fbe92d846298cf93df0b937d3", {})
-        return data["data"]["user"]["username"] if data["data"]["user"] is not None else None
+        try:
+            data = self.graphql_query("d6f4427fbe92d846298cf93df0b937d3", {})
+            return data["data"]["user"]["username"] if data["data"]["user"] is not None else None
+        except (AbortDownloadException, ConnectionException) as err:
+            self.error(f"Error when checking if logged in: {err}")
+            return None
 
     def login(self, user, passwd):
         """Not meant to be used directly, use :meth:`Instaloader.login`.
 
-        :raises InvalidArgumentException: If the provided username does not exist.
         :raises BadCredentialsException: If the provided password is wrong.
-        :raises ConnectionException: If connection to Instagram failed.
         :raises TwoFactorAuthRequiredException: First step of 2FA login done, now call
-           :meth:`Instaloader.two_factor_login`."""
+           :meth:`Instaloader.two_factor_login`.
+        :raises LoginException: An error happened during login (for example, and invalid response).
+           Or if the provided username does not exist.
+
+        .. versionchanged:: 4.12
+           Raises LoginException instead of ConnectionException when an error happens.
+           Raises LoginException instead of InvalidArgumentException when the username does not exist.
+        """
         # pylint:disable=import-outside-toplevel
         import http.client
         # pylint:disable=protected-access
@@ -277,7 +293,7 @@ class InstaloaderContext:
             resp_json = login.json()
 
         except json.decoder.JSONDecodeError as err:
-            raise ConnectionException(
+            raise LoginException(
                 "Login error: JSON decode fail, {} - {}.".format(login.status_code, login.reason)
             ) from err
         if resp_json.get('two_factor_required'):
@@ -289,31 +305,32 @@ class InstaloaderContext:
                                             resp_json['two_factor_info']['two_factor_identifier'])
             raise TwoFactorAuthRequiredException("Login error: two-factor authentication required.")
         if resp_json.get('checkpoint_url'):
-            raise ConnectionException("Login: Checkpoint required. Point your browser to "
-                                      "https://www.instagram.com{} - "
-                                      "follow the instructions, then retry.".format(resp_json.get('checkpoint_url')))
+            raise LoginException(
+                f"Login: Checkpoint required. Point your browser to {resp_json.get('checkpoint_url')} - "
+                f"follow the instructions, then retry."
+            )
         if resp_json['status'] != 'ok':
             if 'message' in resp_json:
-                raise ConnectionException("Login error: \"{}\" status, message \"{}\".".format(resp_json['status'],
-                                                                                               resp_json['message']))
+                raise LoginException("Login error: \"{}\" status, message \"{}\".".format(resp_json['status'],
+                                                                                          resp_json['message']))
             else:
-                raise ConnectionException("Login error: \"{}\" status.".format(resp_json['status']))
+                raise LoginException("Login error: \"{}\" status.".format(resp_json['status']))
         if 'authenticated' not in resp_json:
             # Issue #472
             if 'message' in resp_json:
-                raise ConnectionException("Login error: Unexpected response, \"{}\".".format(resp_json['message']))
+                raise LoginException("Login error: Unexpected response, \"{}\".".format(resp_json['message']))
             else:
-                raise ConnectionException("Login error: Unexpected response, this might indicate a blocked IP.")
+                raise LoginException("Login error: Unexpected response, this might indicate a blocked IP.")
         if not resp_json['authenticated']:
             if resp_json['user']:
                 # '{"authenticated": false, "user": true, "status": "ok"}'
                 raise BadCredentialsException('Login error: Wrong password.')
             else:
                 # '{"authenticated": false, "user": false, "status": "ok"}'
-                # Raise InvalidArgumentException rather than BadCredentialException, because BadCredentialException
+                # Raise LoginException rather than BadCredentialException, because BadCredentialException
                 # triggers re-asking of password in Instaloader.interactive_login(), which makes no sense if the
                 # username is invalid.
-                raise InvalidArgumentException('Login error: User {} does not exist.'.format(user))
+                raise LoginException('Login error: User {} does not exist.'.format(user))
         # '{"authenticated": true, "user": true, "userId": ..., "oneTapPrompt": false, "status": "ok"}'
         session.headers.update({'X-CSRFToken': login.cookies['csrftoken']})
         self._session = session
@@ -351,6 +368,23 @@ class InstaloaderContext:
         if self.sleep:
             time.sleep(min(random.expovariate(0.6), 15.0))
 
+    @staticmethod
+    def _response_error(resp: requests.Response) -> str:
+        extra_from_json: Optional[str] = None
+        with suppress(json.decoder.JSONDecodeError):
+            resp_json = resp.json()
+            if "status" in resp_json:
+                extra_from_json = (
+                    f"\"{resp_json['status']}\" status, message \"{resp_json['message']}\""
+                    if "message" in resp_json
+                    else f"\"{resp_json['status']}\" status"
+                )
+        return (
+            f"{resp.status_code} {resp.reason}"
+            f"{f' - {extra_from_json}' if extra_from_json is not None else ''}"
+            f" when accessing {resp.url}"
+        )
+
     def get_json(self, path: str, params: Dict[str, Any], host: str = 'www.instagram.com',
                  session: Optional[requests.Session] = None, _attempt=1,
                  response_headers: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
@@ -392,7 +426,7 @@ class InstaloaderContext:
                 if (redirect_url.startswith('https://www.instagram.com/accounts/login') or
                     redirect_url.startswith('https://i.instagram.com/accounts/login')):
                     if not self.is_logged_in:
-                        raise LoginRequiredException("Redirected to login page. Use --login.")
+                        raise LoginRequiredException("Redirected to login page. Use --login or --load-cookies.")
                     raise AbortDownloadException("Redirected to login page. You've been logged out, please wait " +
                                                  "some time, recreate the session and try again")
                 if redirect_url.startswith('https://{}/'.format(host)):
@@ -404,21 +438,17 @@ class InstaloaderContext:
                 response_headers.clear()
                 response_headers.update(resp.headers)
             if resp.status_code == 400:
-                raise QueryReturnedBadRequestException("400 Bad Request")
+                raise QueryReturnedBadRequestException(self._response_error(resp))
             if resp.status_code == 404:
-                raise QueryReturnedNotFoundException("404 Not Found")
+                raise QueryReturnedNotFoundException(self._response_error(resp))
             if resp.status_code == 429:
-                raise TooManyRequestsException("429 Too Many Requests")
+                raise TooManyRequestsException(self._response_error(resp))
             if resp.status_code != 200:
-                raise ConnectionException("HTTP error code {}.".format(resp.status_code))
+                raise ConnectionException(self._response_error(resp))
             else:
                 resp_json = resp.json()
             if 'status' in resp_json and resp_json['status'] != "ok":
-                if 'message' in resp_json:
-                    raise ConnectionException("Returned \"{}\" status, message \"{}\".".format(resp_json['status'],
-                                                                                               resp_json['message']))
-                else:
-                    raise ConnectionException("Returned \"{}\" status.".format(resp_json['status']))
+                raise ConnectionException(self._response_error(resp))
             return resp_json
         except (ConnectionException, json.decoder.JSONDecodeError, requests.exceptions.RequestException) as err:
             error_string = "JSON Query to {}: {}".format(path, err)
@@ -607,11 +637,11 @@ class InstaloaderContext:
         else:
             if resp.status_code == 403:
                 # suspected invalid URL signature
-                raise QueryReturnedForbiddenException("403 when accessing {}.".format(url))
+                raise QueryReturnedForbiddenException(self._response_error(resp))
             if resp.status_code == 404:
                 # 404 not worth retrying.
-                raise QueryReturnedNotFoundException("404 when accessing {}.".format(url))
-            raise ConnectionException("HTTP error code {}.".format(resp.status_code))
+                raise QueryReturnedNotFoundException(self._response_error(resp))
+            raise ConnectionException(self._response_error(resp))
 
     def get_and_write_raw(self, url: str, filename: str) -> None:
         """Downloads and writes anonymously-requested raw data into a file.
@@ -637,11 +667,11 @@ class InstaloaderContext:
         else:
             if resp.status_code == 403:
                 # suspected invalid URL signature
-                raise QueryReturnedForbiddenException("403 when accessing {}.".format(url))
+                raise QueryReturnedForbiddenException(self._response_error(resp))
             if resp.status_code == 404:
                 # 404 not worth retrying.
-                raise QueryReturnedNotFoundException("404 when accessing {}.".format(url))
-            raise ConnectionException("HTTP error code {}.".format(resp.status_code))
+                raise QueryReturnedNotFoundException(self._response_error(resp))
+            raise ConnectionException(self._response_error(resp))
 
     @property
     def root_rhx_gis(self) -> Optional[str]:

instaloader/structures.py

@@ -330,7 +330,7 @@ class Post:
         if not self._context.iphone_support:
             raise IPhoneSupportDisabledException("iPhone support is disabled.")
         if not self._context.is_logged_in:
-            raise LoginRequiredException("--login required to access iPhone media info endpoint.")
+            raise LoginRequiredException("Login required to access iPhone media info endpoint.")
         if not self._iphone_struct_:
             data = self._context.get_iphone_json(path='api/v1/media/{}/info/'.format(self.mediaid), params={})
             self._iphone_struct_ = data['items'][0]
@@ -685,6 +685,9 @@ class Post:
         .. versionchanged:: 4.7
            Change return type to ``Iterable``.
         """
+        if not self._context.is_logged_in:
+            raise LoginRequiredException("Login required to access comments of a post.")
+
         def _postcommentanswer(node):
             return PostCommentAnswer(id=int(node['id']),
                                      created_at_utc=datetime.utcfromtimestamp(node['created_at']),
@@ -749,7 +752,7 @@ class Post:
            Require being logged in (as required by Instagram).
         """
         if not self._context.is_logged_in:
-            raise LoginRequiredException("--login required to access likes of a post.")
+            raise LoginRequiredException("Login required to access likes of a post.")
         if self.likes == 0:
             # Avoid doing additional requests if there are no comments
             return
@@ -926,7 +929,7 @@ class Profile:
 
         .. versionadded:: 4.5.2"""
         if not context.is_logged_in:
-            raise LoginRequiredException("--login required to access own profile.")
+            raise LoginRequiredException("Login required to access own profile.")
         return cls(context, context.graphql_query("d6f4427fbe92d846298cf93df0b937d3", {})["data"]["user"])
 
     def _asdict(self):
@@ -980,7 +983,7 @@ class Profile:
         if not self._context.iphone_support:
             raise IPhoneSupportDisabledException("iPhone support is disabled.")
         if not self._context.is_logged_in:
-            raise LoginRequiredException("--login required to access iPhone profile info endpoint.")
+            raise LoginRequiredException("Login required to access iPhone profile info endpoint.")
         if not self._iphone_struct_:
             data = self._context.get_iphone_json(path='api/v1/users/{}/info/'.format(self.userid), params={})
             self._iphone_struct_ = data['user']
@@ -1187,7 +1190,7 @@ class Profile:
         :rtype: NodeIterator[Post]"""
 
         if self.username != self._context.username:
-            raise LoginRequiredException("--login={} required to get that profile's saved posts.".format(self.username))
+            raise LoginRequiredException(f"Login as {self.username} required to get that profile's saved posts.")
 
         return NodeIterator(
             self._context,
@@ -1247,7 +1250,7 @@ class Profile:
         .. versionadded:: 4.10
         """
         if not self._context.is_logged_in:
-            raise LoginRequiredException("--login required to get a profile's followers.")
+            raise LoginRequiredException("Login required to get a profile's followers.")
         self._obtain_metadata()
         return NodeIterator(
             self._context,
@@ -1266,7 +1269,7 @@ class Profile:
         :rtype: NodeIterator[Profile]
         """
         if not self._context.is_logged_in:
-            raise LoginRequiredException("--login required to get a profile's followers.")
+            raise LoginRequiredException("Login required to get a profile's followers.")
         self._obtain_metadata()
         return NodeIterator(
             self._context,
@@ -1285,7 +1288,7 @@ class Profile:
         :rtype: NodeIterator[Profile]
         """
         if not self._context.is_logged_in:
-            raise LoginRequiredException("--login required to get a profile's followees.")
+            raise LoginRequiredException("Login required to get a profile's followees.")
         self._obtain_metadata()
         return NodeIterator(
             self._context,
@@ -1304,7 +1307,7 @@ class Profile:
         .. versionadded:: 4.4
         """
         if not self._context.is_logged_in:
-            raise LoginRequiredException("--login required to get a profile's similar accounts.")
+            raise LoginRequiredException("Login required to get a profile's similar accounts.")
         self._obtain_metadata()
         yield from (Profile(self._context, edge["node"]) for edge in
                     self._context.graphql_query("ad99dd9d3646cc3c0dda65debcd266a7",
@@ -1383,7 +1386,7 @@ class StoryItem:
         if not self._context.iphone_support:
             raise IPhoneSupportDisabledException("iPhone support is disabled.")
         if not self._context.is_logged_in:
-            raise LoginRequiredException("--login required to access iPhone media info endpoint.")
+            raise LoginRequiredException("Login required to access iPhone media info endpoint.")
         if not self._iphone_struct_:
             data = self._context.get_iphone_json(
                 path='api/v1/feed/reels_media/?reel_ids={}'.format(self.owner_id), params={}