Instaloader downloads public Instagram content, and it has no proxy setting. Not a flag, not an argument, not a line in the documentation. Thirty issues on its tracker ask about proxies anyway, which tells you how often people need one. This page is the answer the documentation never gives, plus the part that matters more: the tool's own rate limiter, and why a fresh address so often changes nothing. We read release 4.15.3 on 20 September 2026.
A note on scope. This is about downloading public posts. It is not about logging in, about accounts, or about anything that touches somebody else's account.
Where the proxy goes
export HTTPS_PROXY="http://USER:PASS@GATEWAY_HOST:GATEWAY_PORT"
instaloader profile SOME_PUBLIC_PROFILE
Every request the tool makes goes through a plain session of the standard Python request library, and the tool never turns that library's environment handling off. So the usual variables route it, without touching the code.
The login can travel in the address. A maintainer answered that question directly on the tracker in 2018, on the pull request that would have added a proxy option and was closed three months later for inactivity: the layer underneath already supports basic authentication in the address. For SOCKS the same maintainer pointed at wrapper tools, so a plain HTTP port is the easier choice here.
If you need a different address per instance rather than one for the whole environment, the session object is the place, and the tracker has an old request for exactly that.
What the tool allows itself
Here is the part that decides your afternoon. Instaloader paces itself, with numbers you can read in its source:
| Rule | Value |
|---|---|
| Requests of the "other" query type | 75 per sliding window |
| Requests of the remaining types | 200 per sliding window |
| The sliding window | 11 minutes |
| A separate window for one request type | 30 minutes |
| Wait after a refusal | until the oldest request in the window ages out, plus a few seconds |
Its documentation states the two assumptions behind those numbers: that nothing else is consuming requests at the same time, and that none had been consumed when it started. It even warns that "restarting or reinstantiating Instaloader often within short time is prone to cause a 429".
Why a new address rarely helps
The counters live on the instance. Nothing in them is keyed to an address, so swapping the proxy under a running process neither resets the accounting nor informs it. You have changed what the site sees, and nothing about how fast the tool is willing to go.
That has a useful corollary for diagnosis. If the refusal comes on the very first request after a change, your pacing cannot be the cause, because the accounting starts empty. It is the address.
And the project has something honest to say about addresses. Its own troubleshooting page records an observation rather than a rule: services that by their nature hand out promiscuous addresses, naming cloud, virtual private network and public proxy services, "might be subject to significantly stricter limits for anonymous access". One reporter's reply on the tracker is the fair counterpoint, that residential and mobile addresses are real addresses and should behave differently. Both positions are in the record, and neither is a promise.
The two messages people confuse
One of them is not an error. "Too many queries in the last time" is the tool's own accounting warning you that its budget is nearly spent. The other, a 429, is the site refusing. After a refusal the tool waits for its assumed ban to expire and retries by itself.
If you want different pacing, the documented answer is to subclass the rate controller rather than restarting the process in a loop. Restarting is the thing the documentation warns about.
Which proxy type fits it?
Residential, and one address per process. Our own paired test is unusually direct on this point: of thirteen sites, Instagram was one of four that served a residential address and not our server address.
One address per process is the shape the tool wants. Because its budget is per process, running two downloads means two processes, and each of them should hold its own address for its lifetime. A sticky port gives you that. Write a retry anyway, since a sticky address can still change early when its device leaves the network.
Media downloads are where the bytes go, so a per gigabyte line pays for the pictures and videos rather than for the pacing. The residential proxies page lists the plans and the plan API manages allowed addresses from code.
What breaks
- A refusal on request one. The address, not your pacing.
- More addresses, same speed. The budget is per process. More speed means more processes, each with its own address.
- Refusals right after a restart. A fresh run believes nothing has been consumed. The site disagrees.
- SOCKS does nothing. Not supported directly. Use the HTTP port.
- The variables have no effect. Check that you exported the one matching the scheme, and that nothing in your wrapper disables environment handling.
What this page does not cover
We read the release and the tracker as text and did not run the tool against the site, so we did not measure refusals and we make no claim about how many downloads a given address survives. That the environment variables work rests on the tool never disabling the library's environment handling, not on a captured request. The address quality point is the project's own hedged observation, quoted as such, and the tracker discussion around it is from 2020. The site changes its limits without notice and the project says its own rate controller may change between versions, so we will read this again by 20 October 2026.
Where to go from here
Proxies for yt-dlp covers the other downloader people run into rate limits with, which does take a proxy flag. Proxies for curl_cffi covers the client behind many scrapers, and what a refused tunnel looks like there. Datacenter versus residential is the address decision this page keeps pointing at.
Sources
- The absence of any proxy handling, the plain session that carries every request, and the rate controller with its windows and budgets (instaloader/instaloadercontext.py). The rate controller's assumptions, the observation about shared addresses, and the two messages (docs/troubleshooting.rst). instaloader/instaloader, release v4.15.3 of 26 July 2026, read 20 September 2026.
- Issue 174, the proxy pull request closed in 2018 with the maintainer's note about authentication in the address and about SOCKS wrappers. Issue 459 on wiring one into your own code, issue 654 on a refusal straight after an address change, issue 501 on supplying your own session. Instaloader issue tracker, read 20 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.
