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 user <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