basketcase

BasketCase

Download images and videos from Instagram.

Notable features:

• Stories can be downloaded without triggering the "seen" flag.
• Downloads a high quality version of a profile picture.

"Green Day - Basket Case" on YouTube ;)

Installation methods

pipx

The author prefers pipx, which greatly simplifies user installations while avoiding conflicts with the system.

venv

Or you could simply install it in a virtual environment using venv. I would keep mine at ~/.venv, then I'd use a shell alias to quickly activate it.

zipapp

A pre-built executable for Linux is provided with the releases, and you can just put it in your PATH.

User install

Finally, you can install it from PyPI as a user install. But be aware that some operating systems forbid this practice.

pip install --user basketcase

Command-line usage

basketcase -u "https://instagram.com/p/<post_id>"

Downloaded resources will be stored in the current working directory (i.e. $PWD/basketcase_downloads).

To download from multiple URLs, create a text file (e.g. urls.txt) and populate it with resource URLs:

https://instagram.com/p/<post_id>
https://instagram.com/reel/<reel_id>
https://instagram.com/<username>

basketcase -f ./urls.txt

See --help for more info.

Supported URLs

Supported URL	Description
https://instagram.com/<username>	User profile. Downloads stories from the past 24 hours, and the profile picture.
https://instagram.com/p/<post_id>	Standard feed post
https://instagram.com/reel/<reel_id>	Reels movie
https://instagram.com/stories/highlights/<highlight_id>/	A collection of stories, or "highlights"
https://instagram.com/s/<code>	An alternative URL commonly used for highlighted stories
https://instagram.com/tv/<code>	Similar to reels

Authentication

1. Add a session cookie

basketcase --cookie <session_cookie_id> --cookie-name "my session"
# Added session id: 1

1. Specify its identifier when downloading

basketcase -s 1

List all available sessions with basketcase -l. To disable sessions, use --no-session. If only one exists, it is treated as the default.

User data

Cookies and other application data are kept in your home directory (i.e. ~/.basketcase).

Known limitations

This program relies on the APIs used by the web browser Instagram client, which can change without a notice.

To discover and run all tests in this project, activate the project venv, cd to the project root and run python -m unittest. Test coverage is still low and needs some effort.

Multiple authors, owner is private

Fails to locate a suitable extractor for a standard feed post with multiple authors, in which the owner - or main author - has a private profile you cannot see.

Development setup

This project uses pipenv for dependency and virtual environment management, so make sure it's installed. pipx is a convenient tool to manage your virtual-environment user installations, and it can be used to install pipenv.

1. cd to the project root and run pipenv install --dev.

Package build and upload

1. Increment the version in pyproject.toml.
2. Build the package.

python -m build

1. Commit and push the changes (and a new version tag) to the git repository.
2. Publish it.

python -m twine upload dist/*

Build an executable

With the zipapp module we can build the whole package as an executable file for Linux. The only runtime requirement is Python 3.

1. cd to the project root.
2. Activate the virtual environment.
3. Run sh zipapp.sh.

The executable file basketcase is in the dist folder.