PostShelf documentation

Before you buy

Requirements

PostShelf includes the download tool used for an individual post or Reel. You do not need Xcode, Python or Homebrew for that. The features below have different requirements.

Installation

Install PostShelf

1. Download PostShelf-1.0.0.dmg from your Lemon Squeezy receipt. You can also retrieve it later from My Orders.
2. Open the DMG and drag PostShelf into the Applications folder.
3. Eject the PostShelf disk image, then open PostShelf from Applications.
4. Read the account warning shown on first launch. Continue only if you understand the Instagram account risk.

The app is signed and notarized. macOS should open it normally without a Gatekeeper workaround.

Required for subscriptions

Install gallery-dl

Skip this section if you only download individual post and Reel links. For account, hashtag, Saved, Tagged, Story or Highlight downloads, install gallery-dl with Homebrew:

brew install gallery-dl

Check the installation in Terminal:

gallery-dl --version

If brew is not installed, follow Homebrew's installation instructions first. The gallery-dl formula page lists the current package and install command.

Using the app

Make the first download

One post or Reel

1. Press Command-L.
2. Paste the full Instagram post or Reel URL.
3. Choose Video, Audio or Both.
4. Click Download.

Video keeps the MP4. Audio creates an M4A using macOS media support. Both keeps both files.

Account or hashtag subscription

1. Install gallery-dl and confirm PostShelf finds it.
2. Press Command-N.
3. Enter the account, hashtag or supported Instagram URL.
4. Choose the content and refresh schedule.

Automatic refresh runs only while PostShelf is open. Set it to Never if you prefer to refresh subscriptions yourself.

Signed-in downloads

Instagram login

Saved posts, Following, private media and some Instagram responses need a signed-in session. Open PostShelf > Settings > Downloads and click Sign In. The login form is Instagram's own website.

PostShelf does not read or store your password. Once Instagram accepts the login, PostShelf stores the resulting session cookies in macOS Keychain. During a download it writes them to a temporary, permission-restricted file, passes that file to the downloader, then removes it.

To remove the saved session, use Forget Stored Session under Settings > Downloads.

On your Mac

Files and storage

Downloads go to ~/Pictures/PostShelf by default. Change that under Settings > General. The library index is stored at ~/Library/Application Support/PostShelf/library.json.

PostShelf also creates hidden archive files in the download folder so the same post is not downloaded twice. Audio-only downloads may keep a source video in a hidden .postshelf-source-cache folder. Do not remove those files unless you are prepared for a future refresh to download media again.

Data handling

Privacy

PostShelf does not require an app account and includes no advertising SDK or usage analytics. Its library and downloaded media stay on your Mac. Download requests go from the local gallery-dl or yt-dlp process to Instagram.

If you sign in, the Instagram session cookies are stored in Keychain as described above. PostShelf does not send those cookies to the developer. Lemon Squeezy handles checkout, receipts and download delivery under its privacy policy .

The PostShelf website uses Google Analytics to count visits and see which pages and purchase links people use. The Mac app itself does not include usage analytics.

New versions

Update PostShelf

PostShelf 1.0 does not update itself. Download the current DMG from Lemon Squeezy My Orders , quit PostShelf, then replace the copy in Applications.

Existing customers can access the current product files through My Orders. Replacing the app does not remove the library or the files in your download folder.

When a download fails

Troubleshooting

“gallery-dl was not found”

Install gallery-dl, open Settings > Downloads, then click Check Again. If PostShelf still cannot find it, choose the executable manually.

The subscription says “Needs Attention”

Select the subscription and read the error in its inspector. The downloader's message usually says whether the problem is a missing tool, expired login, unavailable post or Instagram change.

Private or Saved content stopped working

Use Refresh Login under Settings > Downloads. Complete any security check on Instagram itself. A fresh login will not fix a site change that gallery-dl does not understand yet.

The download completed but the file looks missing

Use Download > Open Download Folder or select the subscription and choose Show in Finder. Check the output folder under Settings > General if you changed it.

Instagram changed something

Instagram changes can break a working login or download without warning. A PostShelf, gallery-dl or yt-dlp update may be needed. Do not keep retrying against an account that is receiving security challenges.

PostShelf 1.0

Current limitations

• Location subscriptions can be saved, but they cannot currently download media because the available tools do not expose a working Instagram location extractor.
• Following support is partial. The authenticated route exists, but PostShelf does not yet turn every result into a managed subscription.
• Automatic refresh works while PostShelf is open. There is no menu-bar background service or launch-at-login option.
• There is no subscription export or manual drag ordering.
• Instagram can change or remove access at any time. Continuous compatibility is not guaranteed.

Removal

Uninstall PostShelf

1. If you signed in, use Forget Stored Session first.
2. Quit PostShelf and move it out of Applications.
3. Delete ~/Pictures/PostShelf or your chosen output folder only if you also want to remove downloaded media.
4. Delete ~/Library/Application Support/PostShelf if you want to remove the library index.

Removing the app does not delete downloads or its library data automatically.