instaLooter provides a command line interface, that you can call with the instaLooter command.


In some cases, the instaLooter command is not added into the $PATH after installation. It is possible to perform all the following actions nevertheless by replacing occurences of instaLooter with python -m instaLooter (or python3 -m instaLooter).

Command Line Interface

Download pictures/videos from the profile of a single user:

$ instaLooter <username> [<directory>] [options]

Download pictures/videos tagged with a given #hashtag:

$ instaLooter hashtag <hashtag> <directory> [options]

Download pictures/videos from a single post:

$ instaLooter post <post_token> <directory> [options]

Download pictures/videos in Batch mode:

$ instaLooter batch <batch_file>

Positional Arguments

the username of the Instagram profile to download pictures/videos from.
the hashtag to download pictures/videos from.
the URL or the code of the post to download.
the directory in which to download pictures/videos. Optional for profile download, will then use current directory.
the path to the batch file containing batch download instructions (see the Batch mode page for the format specification).

Options - Credentials

-u USER, --username USER
The username to connect to Instagram with.
-p PASS, --password PASS
The password to connect to Instagram with (will be asked in the shell if the --username option was given without the corresponding --password).

Options - Files

-n NUM, --num-to-dl NUM
Maximum number of new files to download
-j JOBS, --jobs JOBS
Number of parallel threads to use to download files [default: 16]
-T TMPL, --template TMPL
A filename template to use to write the files (see Template). [default: {id}]
-v, --get-videos
Get videos as well as photos
-V, --videos-only
Get videos only (implies --get-videos)
-N, --new
Only look for files newer than the ones in the destination directory (faster).
-t TIME, --time TIME
The time limit within which to download pictures and video (see Time)

Options - Metadata

-d, --dump-json
Save metadata to a JSON file next to downloaded videos and pictures.
-m, --add-metadata
Add date and caption metadata to downloaded pictures (requires PIL or Pillow as well as piexif).
-D, --dump-only
Save only the metadata and no video / picture.
-e, --extended-dump
Always dump the maximum amount of extractable information, at the cost of more time.

Options - Miscellaneous

-q, --quiet
Do not produce any output
-h, --help
Display the help message
Show program version and quit
Print error traceback if any (debug).
Change warning behaviour (same as python -W) [default: default]


The default filename of the pictures and videos on Instagram doesn’t show anything about the file you just downloaded. But using the -T argument allows you to give instaLooter a filename template, using the following format with brackets-enclosed ({}) variable names among:

  • id*² and code² of the instagram id of the media
  • ownerid*, username and fullname of the owner
  • datetime*: the date and time of the post (YYYY-MM-DD hh:mm:ss)
  • date*: the date of the post (YYYY-MM-DD)
  • width* and height*
  • likescount* and commentscount*
*:use these only to quicken download, since fetching the others may take a tad longer (in particular in hashtag download mode).
²:use at least one of these in your filename to make sure the generated filename is unique.

Examples of acceptable values:

$ instaLooter <profile> -T {username}.{datetime}
$ instaLooter <profile> -T {username}-{likescount}-{width}x{height}.{id}
$ instaLooter <profile> -T {username}.{code}.something_constant


The --time parameter can be given either a combination of start and stop date in ISO format (e.g. 2016-12-21:2016-12-18, 2015-03-07:, :2016-08-02) or a special value among: thisday, thisweek, thismonth, thisyear.

Edges are included in the time frame, so if using the following value: --time 2016-05-10:2016-04-03, then all medias will be downloaded including the ones posted the 10th of May 2016 and the 3rd of April 2016.


The --username and --password parameters can be used to log to Instagram. This allows you to download pictures/videos from private profiles you are following. You can either provide your password directly or type it in later for privacy purposes.

$ instaLooter ... --username USERNAME --password PASSWORD
$ instaLooter ... --username USERNAME
Password: # type PASSWORD privately here