If you are trying to download a model via ollama pull
from a corporate network, over a VPN, or through an external proxy server, you have likely encountered errors such as
dial tcp: lookup registry.ollama.ai or
context deadline exceeded.
Ollama does not always correctly pick up system proxy settings by default, and the large sizes of models (ranging from 2 to 70+ GB) exacerbate the problem —
connections drop in the middle of the download. In this article, we will discuss how to properly set environment variables, configure proxies in Docker and systemd,
as well as decode the most common pull errors and how to fix them.
How Ollama Works with the Network and Proxy
Ollama is a client-server application: the local server (ollama serve)
receives commands from the CLI and makes network requests to the model registry registry.ollama.ai and to the CDN where the model layers are stored.
The command ollama pull llama3 actually performs a series of HTTPS requests,
similar to Docker pull: first, it requests the model manifest, then the binary layers (GGUF weight files) are downloaded sequentially or in parallel.
An important nuance: it is the server process of Ollama that performs the network requests, not the CLI command. This means that the environment variables
with proxy settings need to be set where the ollama serve process is running,
not in the terminal from which you invoke ollama pull.
If the service is running as a systemd unit or in a Docker container, exporting the variable in a regular bash session will not affect it —
this is the most common reason why "the proxy seems to be set up, but pull still does not work."
HTTP_PROXY, HTTPS_PROXY, NO_PROXY Environment Variables
Ollama is written in Go, and the standard HTTP library in Go reads proxy settings from classic environment variables:
HTTP_PROXY— proxy for regular HTTP requestsHTTPS_PROXY— proxy for HTTPS requests (this is the one needed for downloading models, as the registry operates over TLS)NO_PROXY— a list of hosts to exclude from proxying (for example, the local Ollama API at 127.0.0.1:11434)
Value format: http://user:password@host:port for authenticated proxies
or socks5://host:port for SOCKS5. Go supports both options,
but for SOCKS5, it is important that the Ollama binary is built with support for this proxy — in most current builds, this is the case, but in case of errors, it is advisable to
first test on HTTP/HTTPS proxies to rule out this variable.
Important: specify the variables in both lower and upper case
(http_proxy and HTTP_PROXY).
Some Linux distributions read only lower case, while Go applications sometimes expect upper case — it is better to set both variants to avoid guessing.
Configuration on Linux and macOS
If you are running Ollama directly from the terminal (not as a system service), it is sufficient to export the variables before starting the server:
export HTTP_PROXY="http://user:[email protected]:8000"
export HTTPS_PROXY="http://user:[email protected]:8000"
export http_proxy="http://user:[email protected]:8000"
export https_proxy="http://user:[email protected]:8000"
export NO_PROXY="localhost,127.0.0.1"
ollama serve &
ollama pull llama3
To keep the settings between sessions, add these lines to ~/.bashrc,
~/.zshrc or ~/.profile
depending on the shell you are using. After editing, run source ~/.bashrc
and restart the Ollama process — environment variables are read only at process startup, hot reload is not provided.
On macOS, if Ollama is installed as an application (not via Homebrew), environment variables from the terminal may not reach the process
launched through the GUI. In this case, it is more reliable to set the variables via launchctl setenv:
launchctl setenv HTTPS_PROXY "http://user:[email protected]:8000"
launchctl setenv HTTP_PROXY "http://user:[email protected]:8000"
# After this, completely restart the Ollama application (exit the tray, not just close the window)
Configuration on Windows
In PowerShell, variables are set for the current session with the command:
$env:HTTP_PROXY="http://user:[email protected]:8000"
$env:HTTPS_PROXY="http://user:[email protected]:8000"
$env:NO_PROXY="localhost,127.0.0.1"
ollama pull mistral
If Ollama is running as a background service (icon in the system tray), session variables are not enough — the service starts at login
before you open PowerShell. You need to set the variables at the user or system level through
"Settings → System → About → Advanced system settings → Environment Variables," after which you should completely terminate the process
ollama.exe via Task Manager and restart the application.
Proxy for Ollama in Docker
If Ollama is running in a container (a common case for server deployments), host environment variables do not automatically get into the container —
they need to be explicitly passed through -e or the environment section
in docker-compose:
docker run -d \
-e HTTP_PROXY="http://user:[email protected]:8000" \
-e HTTPS_PROXY="http://user:[email protected]:8000" \
-e NO_PROXY="localhost,127.0.0.1" \
-v ollama:/root/.ollama \
-p 11434:11434 \
--name ollama ollama/ollama
Similarly in docker-compose.yml:
version: "3.8"
services:
ollama:
image: ollama/ollama
environment:
- HTTP_PROXY=http://user:[email protected]:8000
- HTTPS_PROXY=http://user:[email protected]:8000
- NO_PROXY=localhost,127.0.0.1
volumes:
- ollama:/root/.ollama
ports:
- "11434:11434"
volumes:
ollama:
After changing the variables, the container needs to be recreated (docker compose up -d --force-recreate),
a simple restart is not enough, as environment variables are fixed at the time of container creation.
Proxy for the Ollama systemd Service
On Linux servers, Ollama is often installed as a systemd service via the official install script. In this case, environment variables
are set through an override file, not through export in the terminal:
sudo systemctl edit ollama.service
In the opened editor, add:
[Service]
Environment="HTTP_PROXY=http://user:[email protected]:8000"
Environment="HTTPS_PROXY=http://user:[email protected]:8000"
Environment="NO_PROXY=localhost,127.0.0.1"
Then apply the changes:
sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property Environment
The last command will show what environment variables the process actually sees — a convenient way to ensure that the configuration has been applied, before trying to perform a pull again.
Analyzing Pull Errors and Their Solutions
Let's analyze the most common error messages when downloading models through a proxy and what to do about them.
dial tcp: lookup registry.ollama.ai: no such host
DNS resolution does not work behind the proxy — this usually means that the request is trying to go directly, bypassing the proxy server, or that the machine has no access
to DNS at all (closed corporate network). Solution: ensure that HTTPS_PROXY
is indeed picked up by the process (see the systemctl show command above),
and that the proxy server itself is capable of resolving external domains (SOCKS5 proxies resolve DNS on their side, HTTP proxies do as well, but some local proxies do not).
proxyconnect tcp: dial tcp: connection refused
Ollama is trying to connect to the proxy but is getting refused. Check the port and host for typos, ensure that the proxy server is indeed listening on the specified port externally (not just on localhost), and that the firewall is not blocking outgoing connections to the proxy port.
407 Proxy Authentication Required
The proxy requires a username and password, but they were not provided or were provided incorrectly. Ensure that the environment variable includes the username and password embedded in the URL
in the format http://user:password@host:port, and that special characters in the password
(such as @ or :)
are URL-encoded (%40, %3A).
x509: certificate signed by unknown authority
This is a sign of a corporate proxy with TLS inspection (MITM), which replaces the SSL certificate with its own root. The Go client Ollama does not trust
this certificate. The solution is to add the corporate root certificate to the system's trusted certificate authority store
(on Linux, usually via update-ca-certificates after copying the .crt file to
/usr/local/share/ca-certificates/). Disabling certificate verification globally is not recommended — this opens the door to traffic interception.
context deadline exceeded / i/o timeout when downloading a layer
The connection drops in the middle of downloading a large model layer (often files of 4-40 GB). Such an error almost always indicates instability or low bandwidth of the proxy server, rather than an issue with Ollama itself. Free or overloaded public proxies drop long TCP sessions, especially if the download takes more than a few minutes. In such cases, switching to a more stable channel helps — for example, data center proxies, which provide high speed and stable connections for downloading large files without interruptions.
Which Type of Proxy to Choose for Ollama
The choice of proxy type depends on the reason you need a proxy for Ollama in the first place. If the task is simply to bypass corporate firewall restrictions within your own network, almost any stable HTTP(S) proxy will suffice. But if the goal is to bypass geo-blocking of the model registry or to hide that the request is coming from a data center (some CDNs throttle speeds for known IP ranges of cloud providers), the choice of proxy type becomes critical.
| Proxy Type | Speed | When to Use for Ollama |
|---|---|---|
| Data Center | High | Downloading large model layers (4-40+ GB) without interruptions, testing from different data center locations |
| Residential | Medium | Bypassing geo-restrictions of the registry when data center IPs fall under regional rate limits |
| Mobile | Variable | Last resort when there is a complete block on IP ranges from providers, less effective for large downloads due to speed fluctuations |
For most scenarios with Ollama — when you simply need to reliably download a model weighing tens of gigabytes — the optimal choice remains data center proxies: they provide maximum bandwidth and minimal latency, which is critical when downloading large binary layers. Residential IPs should only be connected if data center addresses are indeed subject to restrictions on the model registry side.
Connection Diagnostics
Before spending time debugging Ollama itself, check the proxy directly using curl — this will eliminate confusion between an application issue and a problem with the proxy server itself:
# Check registry availability through the proxy
curl -v -x http://user:[email protected]:8000 https://registry.ollama.ai/v2/
# Measure download speed through the proxy
curl -x http://user:[email protected]:8000 -o /dev/null -w "%{speed_download}\n" https://registry.ollama.ai/v2/
# Run ollama serve with detailed logging
OLLAMA_DEBUG=1 ollama serve
If curl successfully gets a response, but ollama pull still fails —
the problem is almost certainly that the environment variables did not reach the server process (the service is running under a different user, from a different shell
or as a systemd unit without override). Return to the systemd section and check the output of systemctl show ollama --property Environment.
If curl also drops while downloading a large file or shows unstable speed — the cause is on the proxy server side, and you should consider switching to a more stable proxy provider focused on transferring large volumes of data.
Conclusion
Configuring Ollama behind a proxy comes down to three key points: environment variables must be set specifically for the process
ollama serve, not for the terminal where you invoke pull;
the proxy URL format must include correctly encoded username and password; and in case of certificate errors, you need to add the corporate
root certificate to the trusted store, rather than disabling TLS verification. Most pull errors are not bugs in Ollama itself,
but rather a result of network settings not being applied to the correct process or the proxy server not being able to sustain long transfers of large files.
If your main task is to reliably and quickly download models weighing tens of gigabytes without connection drops, we recommend trying data center proxies — they provide high bandwidth, necessary for downloading large model layers. And if the reason for using a proxy is to bypass geo-restrictions of the model registry, consider residential proxies, which are less likely to fall under regional limits applied to IP ranges of cloud providers.