Twitter-X-Media-Batch-Downloader: original media in bulk

Four ways to run the same downloader

The project is called Twitter/X Media Batch Downloader and its stated purpose is narrow: it downloads original-quality images and videos from Twitter/X accounts.

The delivery options are the interesting part, because there are four of them and they share a purpose. There are native downloads for Windows, macOS and Linux, with a badge for each platform in the README. There is a userscript, for people who are familiar with userscripts, installed from Greasy Fork:

https://greasyfork.org/en/scripts/523157

There is a Chrome extension version in the Chrome Web Store. And there is a web version, available at TwitterDL.app:

https://twitterdl.app

That spread is a deliberate design choice about where the work happens. The userscript and the extension run inside a browser that already has a session with the site, so the browser context is where the code can reach the same endpoints the site itself uses. The desktop application is the same idea with a native shell around it, and the web application is the version for people who do not want to install anything at all.

The homepage is TwitterDL.app, the primary language of the repository is TypeScript, and the licence is GPL-3.0. The releases are v4.9 on 2026-07-16, v5.0.0 on 2026-07-29 and v5.0.1 on 2026-08-18, with the last push to the repository on the same day as the last release.

So the tool is not a script someone wrote for their own account. It is a product with a web front, a browser extension, a userscript and three desktop builds, and the interesting engineering question is the one the README answers first.

The auth token instructions, and the warning above them

The section on obtaining an auth token carries a warning block before the instructions, and the warning is the most important text in the README.

The advice is not to use the main account to obtain the token. A temporary email service is suggested for registering a Twitter account if you need one. Using an auth token or cookies has the potential to get the account suspended. And if too many media files are fetched, it may trigger a rate limit, and the media retrieval will fail.

Those four sentences cover the three risks of the whole project: the account you use can be lost, the volume you pull can be throttled, and the mechanism is deliberately not the supported one.

The procedure itself is six steps. Go to the Twitter website and log into your account. Open the developer tools with F12. Navigate to the Application tab and select Storage and then Cookies. Find the auth_token value and copy it. And do not log out of your account, since a new auth_token will be generated by Twitter.

That last step is the one people get wrong. The token is invalidated when you log out, so an application that stores it and expects it to work tomorrow will find it dead the next morning, and the fix is to log in again and copy the new value.

The mechanism is a session credential, not an API key. There is no developer account, no OAuth application, no scoped permission and no rate limit negotiation, because the tool is not talking to an API, it is replaying the session of a signed-in user.

A Go backend, a TypeScript front end and the OS keyring

The repository layout is small and tells you the architecture: app.go, main.go, wails.json, and directories for backend and frontend, plus go.mod and go.sum.

Wails is the framework that makes a desktop application out of a web front end, and the module confirms it is version 2 of that framework, github.com/wailsapp/wails/v2 at 2.13.0, on Go 1.25.4 with the module named twitterxmediabatchdownloader. The front end is TypeScript, which is what the repository's primary language reflects.

The three direct dependencies are the ones that explain the application's behaviour. Wails is the desktop shell. github.com/zalando/go-keyring is the credential store, and it is the dependency that matters most: the auth token is held in the operating system's keyring, the Credential Manager on Windows, the Keychain on macOS, or the Secret Service on Linux, rather than in a text file next to the application. modernc.org/sqlite is a pure Go SQLite implementation, which is how the download history and the task list are persisted without a database server or a cgo dependency.

The indirect dependencies show the rest of the shape. There is a toast library for desktop notifications, so the application can tell you a download finished. There are the Wails platform libraries, including go-webview2 for the Windows web view and winloader for the Windows loader. There is the Wails development stack with an echo web server and a websocket for the live reload during development. And there is a set of pure Go replacements for the platform libraries, which is what lets the application build without cgo on every platform.

That last detail is a design decision with a user-visible consequence: a cross-platform build that does not need a C toolchain on the target machine.

Why the batch part is the hard part

The name of the project says batch, and the warning about rate limits explains what that costs.

A single media file is a simple request. A batch is a loop, and the loop is where the account risk and the rate limit both come from. The README's warning is explicit that if too many media files are fetched, it may trigger a rate limit and the media retrieval will fail, which means a download run is not a fire-and-forget operation: it is something that can be part way through when the service stops answering.

That has a consequence for how you would use it. A run over one account with a few hundred posts is a different proposition from a run over a list of accounts, and the failure mode is asymmetric, because the first kind of run may fail part way and the second kind may get the account suspended before it finishes.

The other half of the value is the word original. The media that appears in a timeline is served in a compressed, scaled form, and the URL of the original file is a different one, computed from the media record rather than from the rendered post. Recovering those original URLs is the work that makes this tool worth having, since the timeline version is usually the only one a user can easily reach.

The other user-visible detail in the README is the interface itself, which is shown in dark and light screenshots, so the application follows the system appearance rather than forcing one.

Licence, versioning and the 5.0 jump

The project is licensed under GPL-3.0, and the licence file sits at the repository root next to the README.

The version history is where the project's pace shows. v4.9 on 2026-07-16, then v5.0.0 on 2026-07-29, a major release two weeks later, and then v5.0.1 on 2026-08-18, a patch three weeks after that. A major bump followed by a patch inside a month usually means the major was a large feature addition and the patch fixed something in it.

The version scheme itself, a 4.x line and a 5.x line rather than a date based one, tells you the author treats this as a product with a public surface rather than as a script.

The build and release automation is not described in the visible README, but the .github/ directory at the root and the presence of the Wails project file, wails.json, imply the desktop builds are produced by the standard Wails pipeline. The three platform badges in the README, Windows, macOS and Linux, each pointing at the releases page, confirm that all three are shipped rather than one being built locally.

So the project is a small application with a real distribution: a web version for people who want nothing installed, a browser extension for people who want it in the page context, a userscript for the same, and three desktop builds for people who want a native application with the token stored in the system keyring.

Where this tool is the wrong choice

There are cases where downloading media in bulk from Twitter/X is the wrong answer, and the interesting thing is that the README's own warnings point at most of them.

If you want your own archive, the platform's own data export is the sanctioned route, and it covers more than media alone. A media downloader gives you pictures and videos, which is a small part of what an archive is. So if the account is yours, the official export is the better route and it carries none of the risks described here.

If you need a reliable pipeline for a large corpus, the manual token step and the rate limit make this the wrong tool. A script that pastes a session cookie and polls at a rate the service tolerates is not a pipeline, it is a loop that occasionally stops.

If you are doing this at an organisation's scale, the account risk is the stopping point. The README says using an auth token or cookies has the potential to get the account suspended, and an account suspended is not a recoverable engineering problem for somebody else.

The alternative approach, and it is worth stating without pretending the comparison is close, is a hosted download service that handles the session and the rate limits on your behalf. The difference in approach is that a service asks you for the token once and then manages the throttling, at the cost of your credential passing through somebody else's server and of paying for it.

And one boundary to keep in mind: this project is GPL-3.0, so the source is available and the terms of the service you are downloading from are a separate question that neither the licence nor the README answers for you.

Editorial conclusion

Twitter-X-Media-Batch-Downloader suits somebody archiving media from accounts they follow, or working on a dataset of public posts, and who wants the original files rather than the compressed copies in the timeline. It does not suit an organisation that cannot accept the account risk the README itself spells out, since it needs an auth token and the author says plainly that using one has the potential to get the account suspended. Check three things before you use it: which account you obtain the token with, since the README suggests against the main account, how much you intend to fetch, because too many media files can trigger a rate limit and the retrieval will fail, and whether your organisation has a position on third-party clients of a service whose terms you did not write. The last push to the repository was on 2026-08-18 and the newest release is v5.0.1.

Frequently asked questions

Official sources

1. afkarxyz/Twitter-X-Media-Batch-Downloader on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases