gallery-dl for Twitter (X): Config, Cookies, Rate Limits and Fixes

gallery-dl is on PyPI as gallery-dl (version 1.32.19 at the time of writing, Python 3.8 or newer, GPL-2.0-only license). The project also publishes standalone executables, and its README lists optional extras; the one that matters for X on Linux is SecretStorage, which --cookies-from-browser uses to read GNOME keyring passwords for decrypting Chromium cookies.

Sign in to x.com in a regular browser first. gallery-dl then reads that session: --cookies-from-browser firefox (Chromium-based browsers, Firefox and Safari are supported per the README) or --cookies <path> for a Netscape-format cookies.txt exported by a browser extension. Without cookies the extractor falls back to a guest token, which X answers for some single posts and almost nothing else; most timelines come back as "authenticated cookies" required.

URLs it understands. The supported-sites table lists avatars, backgrounds, bookmarks, communities, followers, followed users, hashtags, highlights, home feed, likes, lists, list members, media timelines, notifications, quotes, search results, timelines, single Tweets and user profiles. https://x.com/<user> uses the include option (default timeline); https://x.com/<user>/media reads only the Media tab.

Keep it current. The X extractor changes almost weekly: the releases from late September to late October 2026 (v1.32.14, v1.32.15, v1.32.17 and v1.32.18) each carry X fixes. Most "gallery-dl twitter not working" reports end with "upgrade".

gallery-dl reads config.json from its standard locations (for example ~/.config/gallery-dl/config.json on Linux and macOS, %APPDATA%\gallery-dl\config.json on Windows). Everything for X sits under extractor.twitter. The block below is a sensible starting point for archiving one account's own media; each option and its default is described in docs/configuration.rst.

Two options worth knowing because of our study. cards defaults to false, and in our sample 42.1% of organization posts were link cards whose image lives in the card, not in the post's media list; if you expect a news account's thumbnails, you will not get them without "cards": true. And archive (a general extractor.* option) stores the IDs of downloaded files in a SQLite file so reruns skip them, which keeps a nightly sync short.

Searchers asking about "gallery dl twitter text" usually want the post text next to each file. That is the --write-metadata command-line flag (a JSON file per download) or the metadata post processor; text-tweets only adds posts that have no media.

The most searched gallery-dl X error is AuthenticationError: Login rejected as suspicious. The project's GitHub tracker holds a run of reports with that title from 2024 and 2025 (issues 6218, 6288, 6822, 7042 and 7318 among them). It was X refusing the scripted username-and-password sign-in that older gallery-dl versions performed.

gallery-dl stopped trying. Commit 1ea09058c7, "[twitter] remove login support", shipped in v1.30.10 on October 12, 2025. In the current extractor/twitter.py, the login routine only logs an error: "Login with username & password is no longer supported. Use browser cookies instead." The username and password options in configuration.rst no longer list twitter among the sites that support them. So the fix for the suspicious-login error is not a different password setting; it is to delete username/password from your twitter block, upgrade, and pass cookies.

Which cookies. gallery-dl checks for X's auth_token session cookie and uses the ct0 cookie as the CSRF token (option csrf, default "cookies"). --cookies-from-browser reads them from the browser profile you name; the config form is "cookies": ["firefox"], with optional profile, keyring, Firefox container and domain entries, for example ["chromium", "Private", "kwallet", null, ".twitter.com"] from the docs. With a cookies.txt file, cookies-update (default true) writes refreshed session cookies back to it.

When cookies expire. Signing out of x.com in the browser, or X ending the session, invalidates the cookies. The symptom is the same "authenticated cookies" requirement on every timeline. Sign in again in the browser and rerun; nothing in gallery-dl needs resetting.

What we will not cover. Some guides suggest rotating several accounts' cookies (cookies-select) to spread requests. That multiplies the number of accounts acting on X's limits, which X's rules do not allow, and we do not recommend it. If one session is not enough throughput, the job has outgrown a personal CLI.

Two of the most searched gallery-dl X jobs are personal archives: everything you have liked, and everything you have bookmarked. Both are handled by dedicated extractors in extractor/twitter.py: TwitterLikesExtractor matches https://x.com/<user>/likes, and TwitterBookmarkExtractor matches https://x.com/i/bookmarks. Both read through your session, so both need your cookies. Bookmarked items get a date_bookmarked field in their metadata; likes get user_likes.

Useful details. Since v1.32.17, "replies": "self" works for likes and bookmarks, and /i/history/likes URLs are accepted. Bookmark folders on Premium accounts are an open request on Codeberg at the time of writing, so plan on the main bookmarks list only. include: ["likes"] on a profile URL is the config form of the likes job.

Media from link cards. On news-style accounts, much of what looks like an image is a link card. gallery-dl skips cards by default (cards: false); set true to download images from supported cards, or "ytdl" to hand unsupported card video to yt-dlp. cards-blacklist excludes card types you do not want.

On the API route. Our API returns the timeline, search and single-post media covered below with an API key and no X account. Bookmarks are available through /twitter/bookmarks_v2, which acts on a logged-in session: one /twitter/user_login_v2 login ($0.10, with a proxy you supply) returns login_cookies that you pass along. That call acts as your account, so X can rate-limit, lock or suspend it; keep a human pace, and expect the session to need a fresh login from time to time. There is no endpoint for another user's likes list.

X limits how often a session can call each web endpoint. gallery-dl reads the x-rate-limit-remaining header on every response and, when it gets low or X answers 429, calls its _handle_ratelimit routine. That routine follows the ratelimit option: with the default "wait" it sleeps until the time in x-rate-limit-reset (or 60 seconds if X sent none). That is why a big likes download can sit silent for many minutes: it is waiting, not hung.

Account locks. If X answers "this account is temporarily locked", gallery-dl raises AuthorizationError by default (locked: "abort"); with "wait" it pauses until you press Enter after unlocking the account in a browser. A lock is X telling you the session looked automated; slow down rather than retry.

Resuming. When a timeline run is interrupted, gallery-dl logs a line like "Use '-o cursor=...' to continue downloading from the current position" (option cursor, default true). Pass that value back with -o cursor= to resume. A cursor from one timeline cannot be used on another.

Pace. gallery-dl's general sleep-request option adds a delay between requests if you want one. For X, keep the defaults, run one job at a time per account, and schedule large archives across days instead of forcing them through. retries-api (default 9) controls retries on server errors.

The latest round of reports came in October 2026. GitHub issue 9822, "Twitter broken for url; KeyError: 'legacy'", opened October 19, 2026 on version 1.32.16, showed KeyError: 'legacy' in _tweets_single. The page the reporter saved with --write-pages held a TweetTombstone instead of a post. The maintainer fixed it the same day (commit 6dead76, "fix KeyError: 'legacy' for quote Tweet chains"), and a second commit the next day handled a related KeyError: 'result' on deleted quoted posts. Both fixes are in v1.32.18, released October 25, 2026, and the issue is closed as completed. A separate change in v1.32.18 fixed the search-limit option.

We found claims that the same month's change to X's GraphQL user object (user records without the old legacy block) broke gallery-dl. The issue thread does not show that: its traceback and saved page point to tombstoned and deleted quoted posts, not the user object. Other community scrapers did hit KeyError failures on user fields around the same time, which is covered on our twscrape page.

Where to report now. Release notes link fixes to both GitHub and Codeberg issue numbers, gallery-dl's own "unexpected error" message now points users to codeberg.org/mikf/gallery-dl/issues, and the README's dev install pulls from Codeberg. Open X issues there at the time of writing include an age-restricted-user NotFoundError, bookmark folders on Premium accounts, and a 404 at the end of a user's media timeline.

A troubleshooting order that works. Upgrade (pip install -U gallery-dl). Confirm the cookies are fresh by opening x.com in that same browser profile. Rerun one failing URL with --verbose --write-pages and read the last API error line. Search the tracker for the exception name. Only then change config.

To give the configuration choices above real numbers, we read the latest posts of eight public organization timelines (@NASA, @NatGeo, @PlayStation, @Xbox, @SpaceX, @Nintendo, @Reuters and @espn) and counted what a media downloader would see in each post's extendedEntities.media[]. Of 860 posts, 159 were reposts (excluded, like gallery-dl's default retweets: false), leaving 701 of the accounts' own posts.

53.8% of own posts carried at least one media item, 458 items in all: 231 photos (50.4%), 225 videos (49.1%) and 2 GIFs. Most media posts had one item; 10.6% had two to four. The spread between accounts is the real lesson: @PlayStation put media in 97.1% of its posts, while @Nintendo had media in one post of 118 and @Reuters in 18.6%. Those two accounts post link cards: 116 and 95 card posts with no media item, 42.1% across the sample. gallery-dl with default settings downloads nothing from those posts.

Photos in this sample were large: the median photo's longest side in original_info was 2,048 px, 52.8% were 2,048 px or more, and the largest was 8,000 px. That is what gallery-dl's default size: ["orig", ...] buys you over the large copy; our picture-download guide measured a 3858x2170 photo coming back at 2048x1152 as large and at full size only as orig.

Every one of the 225 videos in the sample listed several files in video_info.variants[]: a median of 5 variants, between 4 and 6. 100% of videos included an HLS playlist (application/x-mpegURL, a .m3u8 URL), and the rest were progressive mp4 renditions at different resolutions, up to 5 per video. Each mp4 variant carries a bitrate; the playlist does not.

Downloaders pick the highest-bitrate mp4. In our sample that best file had a median bitrate of 10.37 Mbps, the 1080p tier (126 of 225 videos). 42 videos, mostly SpaceX launch footage, offered a 2160p file at 25.13 Mbps, and 84.0% of videos topped out at 1080p or higher. The lowest best-file bitrate was 1.28 Mbps. Video length ran from seconds to 292 seconds, median 29.3 s.

What this means for disk. A 30-second video at 10.37 Mbps is about 39 MB; at 25.13 Mbps it is about 94 MB. The two GIFs in the sample came as a single mp4 variant with bitrate 0, which is how X stores animated GIFs; gallery-dl saves them as mp4. gallery-dl's previews option additionally downloads video previews, and videos: false skips video posts entirely.

The snippet below is the selection rule in a few lines of Python. It is what gallery-dl does by default, and what our video downloader tool does for single links.

gallery-dl is the right tool for a personal archive you run by hand. It is a poor base for a product: it needs a logged-in X session, it waits out rate limits on that session's schedule, and it stops working whenever X changes a response until a new release ships. If downloads feed a service, a scheduled pipeline or a customer, use an API that returns the same media objects with an API key and no X account.

The mapping. A profile's media timeline is /twitter/user/last_tweets (or /twitter/user/tweet_timeline by user ID), filtering posts whose extendedEntities.media[] is not empty. A single post or a batch of posts is /twitter/tweets with tweet_ids. A search like gallery-dl's search URLs is /twitter/tweet/advanced_search with filter:media in the query. Media objects carry the same fields gallery-dl reads: type, media_url_https, original_info, and video_info.variants[].

Cost. Tweet endpoints are billed per post returned: 15 credits, which is $0.15 per 1,000 posts, and a full 20-post page costs $0.003. The whole study on this page, 860 posts in 45 requests, cost $0.129. On X's official pay-per-use rate card (docs.x.com/x-api/getting-started/pricing), a post read is $0.005, so the same 860 posts would be $4.30, and 1,000 posts are $5.00 against $0.15, about 33 times more. X's pay-per-use plan is capped at 3 million post reads a month, with Enterprise above that. Downloading the media files themselves from pbs.twimg.com and video.twimg.com is not billed by either.

Rate limits on our side are per API key: 0.2 requests per second before the first payment, 20 once paid, 50 on Scale, 500 on Business. New accounts that pass the automatic bot check get up to $1 of free credits (at most 100,000 credits, no card, one per person or network, expiring after 31 days), enough to read more than 6,000 posts. Plans and credit packs are on the pricing page.

The end-to-end Python script at the bottom of this page pages through an account with has_next_page and next_cursor, skips reposts like gallery-dl's default, saves photos at ?name=orig and videos at the highest mp4 bitrate, and skips files it already has. For concurrency, retries and HLS-only videos at scale, see our bulk media download guide.

Question. What does a media downloader such as gallery-dl actually fetch from typical public organization timelines on X: how many posts carry media, which types, how many variants per video, and at what bitrate?

Accounts and method. Eight public organization accounts: @NASA, @NatGeo, @PlayStation, @Xbox, @SpaceX, @Nintendo, @Reuters and @espn. We read each account's latest posts with /twitter/user/last_tweets (replies excluded, newest first), up to six pages of 20, through a rate-limited read-only client. 45 requests returned 860 posts; 159 reposts were set aside, leaving 701 own posts. Media fields were read from extendedEntities.media[]; link cards from the card field. Collected in 2026.

What the sample cannot show. Eight organization accounts are not a random sample of X: brand and media accounts post more video and higher-bitrate files than most people. Each account's window is its latest posts, so a launch week or a campaign can shift the mix. We did not run gallery-dl against these accounts, and we did not measure X's rate limits on a logged-in session; the gallery-dl behavior described on this page comes from its source code, docs, issues and release notes.

Privacy. Aggregates only, organization accounts only, no analysis of reposted or quoted authors. The analysis script, protocol and results are kept with the study files.