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.3.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.

To download several posts at once, paste one link per line. If a post or Reel link is already on the clipboard, PostShelf fills it in for you.

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.

Saved, Tagged and Following

Click Saved Posts in the sidebar to add your first Saved subscription, or press Command-N and choose Saved Posts, Tagged Posts or Following under Source type. Enter an account name or profile link, then choose the content and refresh schedule. These subscriptions require gallery-dl.

For Saved Posts, use the account you sign in to under Settings > Downloads. Saved Posts and Following need that session. You can also paste https://www.instagram.com/YOUR_USERNAME/saved/ with automatic source detection selected.

While it works

Downloads and Activity

Downloads wait their turn in a tray at the bottom of the library. PostShelf runs one at a time by default and pauses briefly between them, which is gentler on your Instagram account. Change this under Settings > Downloads. Stop one download from the tray, or all of them with Command-Period.

Download > Show Activity lists every finished download. When one fails, select it to see what went wrong, what to try, and the downloader's own messages.

If your connection drops, PostShelf tries again twice. Scheduled checks are skipped while your Mac is offline and resume shortly after it wakes. The queue is saved when you quit, so waiting downloads can resume when you reopen PostShelf.

When Instagram asks you to stop

A login request or security check pauses every download until you sign in again. Rate limits pause the queue for at least one hour, with longer waits after repeated limits. The library shows the reason and when downloads can resume.

A VPN or shared connection can attract more checks. Changing your connection or proxy does not clear a rate-limit pause. Complete security checks on Instagram and give the account time before refreshing again.

Browse your library

Filter by photos, videos or audio, and sort by posting date or download date. Items are grouped by date, and the inspector can be hidden to give the grid more room. Use the arrow keys to move between items, Space to Quick Look and Return to open. Drag a tile to Finder to copy the file. Search matches captions, accounts, hashtags and locations.

Move to another Mac

Choose File > Export Subscriptions, then File > Import Subscriptions on the other Mac. The export contains your subscriptions and their settings, never your Instagram session or downloaded files.

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, with a backup beside it. If the library file is ever damaged, PostShelf restores the backup and keeps the damaged copy. Download history is kept in history.json in the same folder.

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.3 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 its inspector. PostShelf explains whether the problem is an expired login, a security check, rate limiting, an unavailable post, a network problem, a full disk or an Instagram change, and what to try next. Download > Show Activity has the full details.

Asking for help

Choose Help > Copy Diagnostics and paste the result into your email. It lists app and downloader versions and recent results. It does not include your Instagram session, proxy address, captions or file names.

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.

My external drive is disconnected

PostShelf keeps the library index when the download folder is unavailable. Reconnect the drive before refreshing. Saved files are still indexed after a partial or failed download.

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.3

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 running. Turn on the menu bar option in Settings > General to keep it running after closing the library window. Launch at login is not available.
• Subscriptions can be exported and imported. Manual drag ordering is not available.
• 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.