gallery-dl Twitter / X Guide

gallery-dl recognizes several Twitter / X URL types, including a single status, a user's media tab, timelines, likes, bookmarks, lists, searches, and other extractor-specific pages. For a first job, use a public status URL or the account's /media page. Copy the canonical x.com URL from the browser, quote it in the shell, and simulate extraction before writing any files.

Simulation answers the most important early questions: is your installed gallery-dl version recent enough, does the URL map to the intended Twitter extractor, does the page require login, and which files would be selected? Keep the first run small. A whole timeline can contain reposts, replies, quoted posts, videos, and repeated media, so a working extractor is not yet proof that the default scope matches your goal.

gallery-dl --simulate "https://x.com/USERNAME/status/POST_ID"

gallery-dl --simulate "https://x.com/USERNAME/media"

gallery-dl -K "https://x.com/USERNAME/status/POST_ID"

Twitter increasingly limits anonymous timeline access. When gallery-dl reports that authenticated cookies are needed, sign in through the normal website in a browser profile you control, confirm that the target page opens there, and point gallery-dl at that local profile. The preferred command reads the browser cookie database on your device; it does not require pasting raw cookie values into this website.

Close the browser completely if its cookie database is locked, and verify that you selected the same profile that holds the active X session. Expired sessions, additional account challenges, private content, age restrictions, and account-specific access rules can still block extraction. Cookies only reproduce access your account already has; they do not bypass authorization or platform rules.

gallery-dl --cookies-from-browser firefox --simulate "https://x.com/USERNAME/media"

gallery-dl --cookies-from-browser chrome --simulate "https://x.com/USERNAME/media"

gallery-dl --cookies-from-browser edge --simulate "https://x.com/USERNAME/media"

Once a simulation succeeds, choose a predictable destination and add a download archive. The archive records extractor IDs for successful files and skips them on later runs, which is safer than relying only on filenames. Use a limited range for the first real download, inspect the output, and then increase the scope. Keep one archive file for the recurring job instead of creating a new archive every time.

The Twitter extractor can include or exclude replies, reposts, quoted posts, cards, articles, previews, text-only posts, and videos. Defaults can change between releases, so test the exact URL and installed version instead of assuming every timeline behaves identically. Use -K to inspect metadata before designing filename or filter expressions, and keep secret paths or browser profile names out of shared scripts.

gallery-dl --cookies-from-browser firefox --range "1-25" --download-archive "twitter.sqlite3" "https://x.com/USERNAME/media"

gallery-dl --destination "D:/Media/X" --download-archive "twitter.sqlite3" "https://x.com/USERNAME/media"

gallery-dl --write-metadata --download-archive "twitter.sqlite3" "https://x.com/USERNAME/media"

Move options into config only after the command-line version works. The official example configuration currently exposes Twitter settings such as include, replies, retweets, quoted posts, videos, size preference, API retry behavior, and rate-limit handling. A small, reviewed extractor block is easier to maintain than copying every available option and forgetting which values changed behavior.

The example below keeps videos enabled, excludes replies and reposts, waits when the extractor reaches a rate limit, and points to a stable archive. Browser-cookie selection can remain on the command line if different machines or profiles run the job. Validate JSON carefully: comments, trailing commas, and unescaped Windows backslashes make a config invalid.

{
  "extractor": {
    "twitter": {
      "replies": false,
      "retweets": false,
      "quoted": false,
      "videos": true,
      "ratelimit": "wait",
      "archive": "D:/gallery-dl/twitter.sqlite3"
    }
  }
}

gallery-dl --config-ignore --simulate "https://x.com/USERNAME/media"

gallery-dl --config-status

Treat authentication, rate limiting, empty results, and duplicate skipping as different problems. An AuthRequired message usually points to missing or expired cookies. HTTP 429 or a rate-limit message means the extractor should pause rather than retry aggressively. An empty result can come from the wrong URL type, inaccessible content, a restrictive config, or an archive that already contains the media IDs.

Compare one clean simulation with --config-ignore against the same URL using your normal settings. Then add cookies, range, archive, and filters one at a time. This isolates the option that changes the result. Update gallery-dl through the same installation channel you originally used, confirm the version, and check current upstream issues before assuming a platform-side change can be solved by repeated requests.

gallery-dl is a local downloader, not a permission system. Download only media you are authorized to access and reuse, respect privacy and copyright, and follow applicable platform terms and law. Never share cookies, account tokens, private archives, or downloaded personal data. A technically accessible URL is not automatically licensed for republication.

Version-sensitive behavior can change when X changes its website or APIs. On July 30, 2026, this site verified gallery-dl 1.32.8 from the official PyPI metadata and confirmed that the upstream Codeberg Windows and Linux release files return HTTP 200 with the expected executable filenames and sizes. Recheck the official release and extractor documentation whenever a previously working command changes.