gallery-dl has the proxy option that users of other downloaders ask for and do not get: the metadata requests and the file downloads can be routed separately. On a line billed by the gigabyte, that single setting is most of your bill. We read release 1.32.13 on 20 September 2026, one day after it shipped.
Where the proxy goes
| Setting | What it covers | Default |
|---|---|---|
extractor.*.proxy | all outgoing requests | none |
downloader.*.proxy | file downloads only | the extractor's proxy |
extractor.*.proxy-env | reads HTTP_PROXY, HTTPS_PROXY, NO_PROXY and Windows settings | true |
extractor.*.source-address | which local address to bind to | none |
The main option takes three shapes. A single string routes everything. An object maps a scheme to an address. And a key may name a scheme and a host together, which routes one site and leaves the rest alone:
{
"extractor": {
"proxy": {
"https://www.example-host.com": "http://USER:PASS@GATEWAY_HOST:GATEWAY_PORT"
}
}
}
If your address has no scheme, the tool assumes plain HTTP. That is documented rather than left to chance, which is rarer than it should be in this class of tool.
Two halves, two proxies
The downloader inherits the extractor's proxy, and you can override it. The documentation gives the interesting case in one line: "Disable the use of a proxy for file downloads by explicitly setting this option to null."
{
"extractor": {"proxy": "http://USER:PASS@GATEWAY_HOST:GATEWAY_PORT"},
"downloader": {"proxy": null}
}
That sends the small requests through your line and pulls the files directly. Users of a large video downloader asked for exactly this, in those words, because "using a proxy for downloading large media files consumes a lot of bandwidth unnecessarily". Their request was closed as not planned in September 2026. Here it is a documented setting, and we wrote about that other tool on its own page.
Which half do you actually want routed?
It depends on which request is being refused, and the answer is often the opposite of the cheap one.
If the host refuses your server address outright, the file request is the one being refused, so the proxy has to cover the download. In our own paired test, the image host in our set served a residential address and not our server. That is the expensive case: the bytes go through the line.
If the host serves you fine but limits how often you ask, it is the metadata requests that need the address, and the files can come down directly. That is the cheap case, and it is the one this setting was made for.
So test before you decide. Fetch one file with the proxy off for downloads. If it arrives, you are in the cheap case.
Which proxy type fits it?
Residential, for hosts that refuse a hosting address, and only for the half that needs it. Our test is the size of the effect: 4 of 13 answers changed, and four sites refused both address types.
The per-host form is the other half of the saving. Route the one site that needs it, leave everything else direct, and your line carries a fraction of the run. On a per gigabyte plan that is the difference between a rounding error and a real bill.
If you go the other way and route the downloads, size the plan for the gallery rather than the page count. A sticky port suits a long run against one host, with a retry because a sticky address can change early when its device leaves the network. The residential proxies page lists the plans, and the plan API manages allowed addresses from code.
What breaks
- A SOCKS address fails. The SOCKS extra is not installed. It is optional, not part of the base install.
- The proxy applies where you did not want it. The downloader inherits the extractor's proxy unless you say otherwise.
- Your environment variables are used unexpectedly. They are read by default, along with the Windows system settings. Set the environment switch to false.
- A per-host key does nothing. The key needs a scheme and a host, not a bare host.
- You wanted a different local address, not a proxy. That is a separate setting.
What this page does not cover
We read the release as text and did not run the tool, so we did not measure the traffic saved by routing only the metadata, and we did not test a SOCKS address or a per-host key against a live site. Our address measurement used plain requests against one image host rather than this tool against many, so it shows what an address changes in general rather than per site. This project ships weekly and the release we read was a day old, so check your version against anything written about it, including this.
Where to go from here
Proxies for cobalt is the downloader whose users wanted this setting and did not get it. Proxies for yt-dlp covers the video downloader with the richest proxy flags of the three. Proxies for Instaloader covers one with no proxy option at all, and why its rate limiter matters more.
Sources
- The proxy option and its three shapes, the note about a missing scheme, the environment switch, the local address option (docs/configuration.rst, extractor section), and the separate download proxy with its null case (same file, downloader section). The SOCKS extra (setup.py) and the optional dependency list (README.rst). mikf/gallery-dl, release v1.32.13 of 19 September 2026, read 20 September 2026.
- The closed request for a metadata-only proxy in another downloader. imputnet/cobalt issue 1421, closed as not planned on 16 September 2026.
- Our paired address test of 19 September 2026: 16 URLs, plain requests, two runs from our server and two through a residential line of our house plan. Raw output is kept in the research folder of our OpenClaw page.
- Plans, allowed addresses and sticky sessions. HProxy documentation, hproxy.com/docs, 20 September 2026.
