Download Pictures from Instagram

Here we describe how to use Instaloader to download pictures from Instagram. If you do not have Instaloader installed yet, see Install Instaloader.

Basic Usage

To download all pictures and videos of a profile, as well as the profile picture, do

instaloader profile [profile ...]

where profile is the name of a profile you want to download. Instead of only one profile, you may also specify a list of profiles.

To later update your local copy of that profiles, you may run

instaloader --fast-update profile [profile ...]

If --fast-update is given, Instaloader stops when arriving at the first already-downloaded picture.

When updating profiles, Instaloader automatically detects profile name changes and renames the target directory accordingly.

Instaloader can also be used to download private profiles. To do so, invoke it with

instaloader --login=your_username profile [profile ...]

When logging in, Instaloader stores the session cookies in a file in your temporary directory, which will be reused later the next time --login is given. So you can download private profiles non-interactively when you already have a valid session cookie file.

What to Download

Instaloader supports the following targets:

  • profile

    Public profile, or private profile with --login.

    If an already-downloaded profile has been renamed, Instaloader automatically finds it by its unique ID and renames the folder accordingly.

    Besides the profile’s posts, its current profile picture is downloaded. For each profile you download,

    • --stories

      instructs Instaloader to also download the user’s stories,

    • --highlights

      to download highlights of each profile that is downloaded, and

    • --tagged

      to download posts where the user is tagged.

  • "#hashtag"

    Posts with a certain hashtag (the quotes are usually necessary),

  • %location id

    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 --login.

    New in version 4.2.

  • :stories

    The currently-visible stories of your followees (requires --login),

  • :feed

    Your feed (requires --login),

  • :saved

    Posts which are marked as saved (requires --login),

  • @profile

    All profiles that are followed by profile, i.e. the followees of profile (requires --login).

  • -post

    The single post with the given shortcode. Must be preceeded by -- in the argument list to not be mistaken as an option flag.

    New in version 4.1.

Instaloader goes through all media matching the specified targets and downloads the pictures and videos and their captions. You can specify

  • --comments

    also download comments of each post,

  • --geotags

    download geotags of each post and save them as Google Maps link (requires --login),

For a reference of all supported command line options, see Command Line Options.

Filename Specification

For each target, Instaloader creates a directory named after the target, i.e. profile, #hashtag, %location id, :feed, etc. and therein saves the posts in files named after the post’s timestamp.

--dirname-pattern allows to configure the directory name of each target. The default is --dirname-pattern={target}. In the dirname pattern, the token {target} is replaced by the target name, and {profile} is replaced by the owner of the post which is downloaded.

--filename-pattern configures the path of the post’s files relative to the target directory that is specified with --dirname-pattern. The default is --filename-pattern={date_utc}_UTC. The tokens {target} and {profile} are replaced like in the dirname pattern. The following tokens are defined for usage with --filename-pattern:

  • {target}

    Target name (as given in Instaloader command line)

  • {profile} (same as {owner_username})

    Owner of the Post / StoryItem.

  • {owner_id}

    Unique integer ID of owner profile.

  • {shortcode}

    Shortcode (identifier string).

  • {mediaid}

    Integer representation of shortcode.

  • {date_utc} (same as {date})

    Creation time in UTC timezone. strftime()-style formatting options are supported as format specifier. The default date format specifier used by Instaloader is:

    {date_utc:%Y-%m-%d_%H-%M-%S}
    

For example, encode the poster’s profile name in the filenames with:

instaloader --filename-pattern={date_utc}_UTC_{profile} "#hashtag"

As another example, you may instruct Instaloader to store posts in a PROFILE/YEAR/SHORTCODE.jpg directory structure:

instaloader --dirname-pattern={profile} --filename-pattern={date_utc:%Y}/{shortcode} <target> ...

Filter Posts

The options --post-filter and --storyitem-filter allows to specify criteria that posts or story items have to meet to be downloaded. If not given, all posts are downloaded.

The filter string must be a Python boolean expression where the attributes from Post or StoryItem respectively are defined.

Id est, the following attributes can be used with both --post-filter and --storyitem-filter:

  • owner_username (str), owner_id (int)

    Owner profile username / userid.

  • date_utc (datetime), date_local (datetime)

    Creation timestamp. Since datetime objects can be created inside filter strings, this easily allows filtering by creation date. E.g.:

    instaloader --post-filter="date_utc <= datetime(2018, 5, 31)" target
    
  • is_video (bool)

    Post/StoryItem is a video. For example, you may skip videos:

    instaloader --post-filter="not is_video" target
    

    This is not the same as --no-videos and --no-video-thumbnails, since sidecar posts (posts that contain multiple pictures/videos in one post) have this attribute set to False.

As --post-filter, the following attributes can be used additionally:

  • viewer_has_liked (bool)

    Whether user (with --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
    
  • likes (int), comments (int)

    Likes count / Comments count. You might only want to download posts that either you liked or were liked by many others**:

    instaloader --login=your_username --post-filter="likes>100 or viewer_has_liked" profile
    
  • caption_hashtags (list of str) / caption_mentions (list of str)

    #hashtags or @mentions (lowercased) in the Post’s caption. For example, to download posts of kittens that are cute:

    instaloader --post-filter="'cute' in caption_hashtags" "#kitten"
    
  • tagged_users (list of str)

    Lowercased usernames that are tagged in the Post.

For --storyitem-filter, the following additional attributes are defined:

Metadata Text Files

Unless --no-captions is given, Instaloader creates a .txt file along with each post where the Post’s caption is saved.

You can customize what metadata to save for each Post or StoryItem with --post-metadata-txt and --storyitem-metadata-txt. The default is --post-metadata-txt={caption} and no storyitem metadata txt. These strings are formatted similar as in the Filename Specification and the result is saved in text files, unless it is empty.

Specifying these options multiple times results in output having multiple lines, in the order they were given to Instaloader.

The field names are evaluated to Post or StoryItem attributes, and as such, the same fields are supported as in Filename Specification and Filter Posts.

For example, to save the current number of likes for each post, rather than the post’s caption:

instaloader --post-metadata-txt="{likes} likes." <target>

Note that with this feature, it is possible to easily and fastly 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

Instaloader as Cronjob

Instaloader is suitable for running as a cronjob to periodically update your personal Instagram archive. The --quiet option disables user interactions and logging of non-error messages. To non-interactively use Instaloader logged-in, create a session file, e.g. in your home directory:

instaloader --login=your_username --sessionfile=~/.instaloader-session

Then use the same parameters in your cronjob to load the session and download the given targets:

instaloader --login=your_username --sessionfile=~/.instaloader-session --quiet <target> [...]

Without --sessionfile option, Instaloader saves the session file in a path within your temporary directory.

Programming Instaloader

If your task cannot be done with the command line interface of Instaloader, consider taking a look at the Python Module instaloader. Instaloader exposes its internally used methods and structures, making it a powerful and intuitive Python API for Instagram, allowing to further customize obtaining media and metadata.

Also see Advanced Instaloader Examples, where we collect example scripts that use Instaloader to achieve more complex tasks.

Next Section

Command Line Options

Table of Contents