Instaloader
(Main Class)¶
-
class
Instaloader
(sleep=True, quiet=False, user_agent=None, dirname_pattern=None, filename_pattern=None, download_pictures=True, download_videos=True, download_video_thumbnails=True, download_geotags=False, download_comments=False, save_metadata=True, compress_json=True, post_metadata_txt_pattern=None, storyitem_metadata_txt_pattern=None, max_connection_attempts=3, request_timeout=300.0, rate_controller=None, resume_prefix='iterator', check_resume_bbd=True, slide=None, fatal_status_codes=None, iphone_support=True, title_pattern=None, sanitize_paths=False)¶ Instaloader Class.
- Parameters
user_agent (
Optional
[str
]) –--user-agent
dirname_pattern (
Optional
[str
]) –--dirname-pattern
, default is{target}
filename_pattern (
Optional
[str
]) –--filename-pattern
, default is{date_utc}_UTC
title_pattern (
Optional
[str
]) –--title-pattern
, default is{date_utc}_UTC_{typename}
ifdirname_pattern
contains{target}
or{profile}
,{target}_{date_utc}_UTC_{typename}
otherwise.download_pictures – not
--no-pictures
download_videos (
bool
) – not--no-videos
download_video_thumbnails (
bool
) – not--no-video-thumbnails
download_comments (
bool
) –--comments
save_metadata (
bool
) – not--no-metadata-json
compress_json (
bool
) – not--no-compress-json
post_metadata_txt_pattern (
Optional
[str
]) –--post-metadata-txt
, default is{caption}
. Set to empty string to avoid creation of post metadata txt file.storyitem_metadata_txt_pattern (
Optional
[str
]) –--storyitem-metadata-txt
, default is empty (=none)max_connection_attempts (
int
) –--max-connection-attempts
request_timeout (
float
) –--request-timeout
, set per-request timeout (seconds)rate_controller (
Optional
[Callable
[[InstaloaderContext
],RateController
]]) – Generator for aRateController
to override rate controlling behaviorresume_prefix (
Optional
[str
]) –--resume-prefix
, or None for--no-resume
.check_resume_bbd (
bool
) – Whether to check the date of expiry of resume files and reject them if expired.fatal_status_codes (
Optional
[List
[int
]]) –--abort-on
iphone_support (
bool
) – not--no-iphone
sanitize_paths (
bool
) –--sanitize-paths
-
context
¶ The associated
InstaloaderContext
with low-level communication functions and logging.
-
anonymous_copy
()¶ Yield an anonymous, otherwise equally-configured copy of an Instaloader instance; Then copy its error log.
-
close
()¶ Close associated session objects and repeat error log.
-
download_pic
(filename, url, mtime, filename_suffix=None, _attempt=1)¶ Downloads and saves picture with given url under given directory with given timestamp. Returns true, if file was actually downloaded, i.e. updated.
- Return type
-
save_metadata_json
(filename, structure)¶ Saves metadata JSON file of a structure.
- Return type
None
-
update_comments
(filename, post)¶ - Return type
None
-
save_caption
(filename, mtime, caption)¶ Updates picture caption / Post metadata info
- Return type
None
-
save_location
(filename, location, mtime)¶ Save post location name and Google Maps link.
- Return type
None
-
format_filename_within_target_path
(target, owner_profile, identifier, name_suffix, extension)¶ Returns a filename within the target path.
New in version 4.5.
-
download_title_pic
(url, target, name_suffix, owner_profile, _attempt=1)¶ Downloads and saves a picture that does not have an association with a Post or StoryItem, such as a Profile picture or a Highlight cover picture. Modification time is taken from the HTTP response headers.
New in version 4.3.
- Return type
None
-
download_profilepic_if_new
(profile, latest_stamps)¶ Downloads and saves profile pic if it has not been downloaded before.
- Parameters
latest_stamps (
Optional
[LatestStamps
]) – Database with the last downloaded data. If not present, the profile pic is downloaded unless it already exists
New in version 4.8.
- Return type
None
-
download_profilepic
(profile)¶ Downloads and saves profile pic.
- Return type
None
-
download_highlight_cover
(highlight, target)¶ Downloads and saves Highlight cover picture.
New in version 4.3.
- Return type
None
-
download_hashtag_profilepic
(hashtag)¶ Downloads and saves the profile picture of a Hashtag.
New in version 4.4.
- Return type
None
-
save_session
()¶ Saves internally stored
requests.Session
object todict
.- Raises
LoginRequiredException – If called without being logged in.
New in version 4.10.
- Return type
-
load_session
(username, session_data)¶ Internally stores
requests.Session
object fromdict
.New in version 4.10.
- Return type
None
-
save_session_to_file
(filename=None)¶ Saves internally stored
requests.Session
object.- Parameters
filename (
Optional
[str
]) – Filename, or None to use default filename.- Raises
LoginRequiredException – If called without being logged in.
- Return type
None
-
load_session_from_file
(username, filename=None)¶ Internally stores
requests.Session
object loaded from file.If filename is None, the file with the default session path is loaded.
- Raises
FileNotFoundError – If the file does not exist.
- Return type
None
-
test_login
()¶ Returns the Instagram username to which given
requests.Session
object belongs, or None.
-
login
(user, passwd)¶ Log in to instagram with given username and password and internally store session object.
- Raises
InvalidArgumentException – If the provided username does not exist.
BadCredentialsException – If the provided password is wrong.
ConnectionException – If connection to Instagram failed.
TwoFactorAuthRequiredException – First step of 2FA login done, now call
Instaloader.two_factor_login()
.
- Return type
None
-
two_factor_login
(two_factor_code)¶ Second step of login if 2FA is enabled. Not meant to be used directly, use
Instaloader.two_factor_login()
.- Raises
InvalidArgumentException – No two-factor authentication pending.
BadCredentialsException – 2FA verification code invalid.
New in version 4.2.
- Return type
None
-
format_filename
(item, target=None)¶ Format filename of a
Post
orStoryItem
according tofilename-pattern
parameter.New in version 4.1.
-
download_post
(post, target)¶ Download everything associated with one instagram post node, i.e. picture, caption and video.
-
get_stories
(userids=None)¶ Get available stories from followees or all stories of users whose ID are given. Does not mark stories as seen. To use this, one needs to be logged in
-
download_stories
(userids=None, fast_update=False, filename_target=':stories', storyitem_filter=None, latest_stamps=None)¶ Download available stories from user followees or all stories of users whose ID are given. Does not mark stories as seen. To use this, one needs to be logged in
- Parameters
userids (
Optional
[List
[Union
[int
,Profile
]]]) – List of user IDs or Profiles to be processed in terms of downloading their storiesfast_update (
bool
) – If true, abort when first already-downloaded picture is encounteredfilename_target (
Optional
[str
]) – Replacement for {target} in dirname_pattern and filename_pattern or None if profile name should be used insteadstoryitem_filter (
Optional
[Callable
[[StoryItem
],bool
]]) – function(storyitem), which returns True if given StoryItem should be downloadedlatest_stamps (
Optional
[LatestStamps
]) – Database with the last times each user was scraped
- Raises
LoginRequiredException – If called without being logged in.
Changed in version 4.8: Add latest_stamps parameter.
- Return type
None
-
download_storyitem
(item, target)¶ Download one user story.
-
get_highlights
(user)¶ Get all highlights from a user. To use this, one needs to be logged in.
New in version 4.1.
-
download_highlights
(user, fast_update=False, filename_target=None, storyitem_filter=None)¶ Download available highlights from a user whose ID is given. To use this, one needs to be logged in.
New in version 4.1.
Changed in version 4.3: Also downloads and saves the Highlight’s cover pictures.
- Parameters
user (
Union
[int
,Profile
]) – ID or Profile of the user whose highlights should get downloaded.fast_update (
bool
) – If true, abort when first already-downloaded picture is encounteredfilename_target (
Optional
[str
]) – Replacement for {target} in dirname_pattern and filename_pattern or None if profile name and the highlights’ titles should be used insteadstoryitem_filter (
Optional
[Callable
[[StoryItem
],bool
]]) – function(storyitem), which returns True if given StoryItem should be downloaded
- Raises
LoginRequiredException – If called without being logged in.
- Return type
None
-
posts_download_loop
(posts, target, fast_update=False, post_filter=None, max_count=None, total_count=None, owner_profile=None, takewhile=None)¶ Download the Posts returned by given Post Iterator.
New in version 4.4.
Changed in version 4.5: Transparently resume an aborted operation if posts is a
NodeIterator
.Changed in version 4.8: Add takewhile parameter.
- Parameters
fast_update (
bool
) –--fast-update
.post_filter (
Optional
[Callable
[[Post
],bool
]]) –--post-filter
.max_count (
Optional
[int
]) – Maximum count of Posts to download (--count
).total_count (
Optional
[int
]) – Total number of posts returned by given iterator.owner_profile (
Optional
[Profile
]) – Associated profile, if any.takewhile (
Optional
[Callable
[[Post
],bool
]]) – Expression evaluated for each post. Once it returns false, downloading stops.
- Return type
None
-
get_feed_posts
()¶ Get Posts of the user’s feed.
- Return type
- Returns
Iterator over Posts of the user’s feed.
- Raises
LoginRequiredException – If called without being logged in.
-
download_feed_posts
(max_count=None, fast_update=False, post_filter=None)¶ Download pictures from the user’s feed.
Example to download up to the 20 pics the user last liked:
loader = Instaloader() loader.load_session_from_file('USER') loader.download_feed_posts(max_count=20, fast_update=True, post_filter=lambda post: post.viewer_has_liked)
- Parameters
- Raises
LoginRequiredException – If called without being logged in.
- Return type
None
-
download_saved_posts
(max_count=None, fast_update=False, post_filter=None)¶ Download user’s saved pictures.
- Parameters
- Raises
LoginRequiredException – If called without being logged in.
- Return type
None
-
get_location_posts
(location)¶ Get Posts which are listed by Instagram for a given Location.
- Return type
- Returns
Iterator over Posts of a location’s posts
- Raises
LoginRequiredException – If called without being logged in.
New in version 4.2.
Changed in version 4.2.9: Require being logged in (as required by Instagram)
-
download_location
(location, max_count=None, post_filter=None, fast_update=False)¶ Download pictures of one location.
To download the last 30 pictures with location 362629379, do:
loader = Instaloader() loader.download_location(362629379, max_count=30)
- Parameters
location (
str
) – Location to download, as Instagram numerical IDmax_count (
Optional
[int
]) – Maximum count of pictures to downloadpost_filter (
Optional
[Callable
[[Post
],bool
]]) – function(post), which returns True if given picture should be downloadedfast_update (
bool
) – If true, abort when first already-downloaded picture is encountered
- Raises
LoginRequiredException – If called without being logged in.
New in version 4.2.
Changed in version 4.2.9: Require being logged in (as required by Instagram)
- Return type
None
-
get_explore_posts
()¶ Get Posts which are worthy of exploring suggested by Instagram.
- Returns
Iterator over Posts of the user’s suggested posts.
- Return type
- Raises
LoginRequiredException – If called without being logged in.
-
get_hashtag_posts
(hashtag)¶ Get Posts associated with a #hashtag.
Deprecated since version 4.4: Use
Hashtag.get_posts_resumable()
.
-
download_hashtag
(hashtag, max_count=None, post_filter=None, fast_update=False, profile_pic=True, posts=True)¶ Download pictures of one hashtag.
To download the last 30 pictures with hashtag #cat, do:
loader = Instaloader() loader.download_hashtag('cat', max_count=30)
- Parameters
hashtag (
Union
[Hashtag
,str
]) – Hashtag to download, as instance ofHashtag
, or string without leading ‘#’max_count (
Optional
[int
]) – Maximum count of pictures to downloadpost_filter (
Optional
[Callable
[[Post
],bool
]]) – function(post), which returns True if given picture should be downloadedfast_update (
bool
) – If true, abort when first already-downloaded picture is encounteredprofile_pic (
bool
) – not--no-profile-pic
.posts (
bool
) – not--no-posts
.
Changed in version 4.4: Add parameters profile_pic and posts.
- Return type
None
-
download_tagged
(profile, fast_update=False, target=None, post_filter=None, latest_stamps=None)¶ Download all posts where a profile is tagged.
New in version 4.1.
Changed in version 4.8: Add latest_stamps parameter.
- Return type
None
-
download_igtv
(profile, fast_update=False, post_filter=None, latest_stamps=None)¶ Download IGTV videos of a profile.
New in version 4.3.
Changed in version 4.8: Add latest_stamps parameter.
- Return type
None
-
load_profile_id
(profile_name)¶ Load ID of profile from profile directory.
New in version 4.8.
-
save_profile_id
(profile)¶ Store ID of profile on profile directory.
New in version 4.0.6.
-
check_profile_id
(profile_name, latest_stamps=None)¶ Consult locally stored ID of profile with given name, check whether ID matches and whether name has changed and return current name of the profile, and store ID of profile.
- Parameters
profile_name (
str
) – Profile namelatest_stamps (
Optional
[LatestStamps
]) – Database of downloaded data. If present, IDs are retrieved from it, otherwise from the target directory
- Return type
- Returns
Instance of current profile
Changed in version 4.8: Add latest_stamps parameter.
-
download_profiles
(profiles, profile_pic=True, posts=True, tagged=False, igtv=False, highlights=False, stories=False, fast_update=False, post_filter=None, storyitem_filter=None, raise_errors=False, latest_stamps=None)¶ High-level method to download set of profiles.
- Parameters
profile_pic (
bool
) – not--no-profile-pic
.posts (
bool
) – not--no-posts
.highlights (
bool
) –--highlights
.fast_update (
bool
) –--fast-update
.post_filter (
Optional
[Callable
[[Post
],bool
]]) –--post-filter
.storyitem_filter (
Optional
[Callable
[[Post
],bool
]]) –--post-filter
.raise_errors (
bool
) – WhetherLoginRequiredException
andPrivateProfileNotFollowedException
should be raised or catched and printed withInstaloaderContext.error_catcher()
.latest_stamps (
Optional
[LatestStamps
]) –--latest-stamps
.
New in version 4.1.
Changed in version 4.3: Add igtv parameter.
Changed in version 4.8: Add latest_stamps parameter.
-
download_profile
(profile_name, profile_pic=True, profile_pic_only=False, fast_update=False, download_stories=False, download_stories_only=False, download_tagged=False, download_tagged_only=False, post_filter=None, storyitem_filter=None)¶ Download one profile
Deprecated since version 4.1: Use
Instaloader.download_profiles()
.- Return type
None
-
interactive_login
(username)¶ Logs in and internally stores session, asking user for password interactively.
- Raises
LoginRequiredException – when in quiet mode.
InvalidArgumentException – If the provided username does not exist.
ConnectionException – If connection to Instagram failed.
- Return type
None