basketcase 8.0.1

Download media from Instagram

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.

pipx install basketcase

venv

Or you could simply install it in a virtual environment created with venv.

pip install basketcase

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 get "https://instagram.com/p/<post_id>"

Downloaded resources will be stored in the current working directory by default. Override with the get --output option.

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 get ./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

Session management

To retrieve your Instagram cookies, follow these steps:

1. Navigate to instagram.com on your browser.
2. Open up Developer Tools, switch to the Network tab, then reload the page.
3. On the list, find the initial request that returns HTML, and inspect its request headers.
4. Copy the value of the Cookie header and put it in a text file (e.g. cookies.txt).

basketcase session add-cookies ./cookies.txt --set-name "jane.doe"
# New session created (id=1) with 10 cookie(s)

This is the recommended method, since we should try to look like a real browser as much as we can to avoid "automated behavior" warnings.

Alternatively, add a single sessionid cookie.

basketcase session add-cookie "COOKIE_VALUE" --set-name "john.doe"
# New session created (id=1) with one 'sessionid' cookie

Specify its identifier when downloading.

basketcase get -s 1 URL_OR_FILE

List all available sessions with basketcase session list.

To disable sessions, use get --no-session.

If only one exists, it is treated as the default.

When the instance is closed (BasketCase.close()) or the script exits, cookies from the HTTP client are saved in the database. This keeps your cookies up-to-date.

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. Install build dependencies

These must be installed using the system package manager. The package name examples listed below are from Debian.

• Python development headers and libraries (e.g. python3-dev).
• lxml requires libxml2 and libxslt, as documented here (e.g. libxml2-dev libxslt-dev).
• cffi requires libffi (e.g. libffi-dev).

Setup the environment

cd to the project root, then run pipenv install --dev.

Package build and upload

First, increment the version in pyproject.toml.

Then build the package.

python -m build

If that succeeds, commit and push the changes, then tag the release.

git tag -a <version> -m 'Briefly describe the changes'

Now publish it.

python -m twine upload dist/*

Finally, merge next into main.

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.