← Back to Blog

Ollama via Proxy: How to Configure HTTP_PROXY and Fix Model Pull Errors

A detailed guide on configuring Ollama behind a proxy server — from environment variables to diagnosing pull model errors and selecting the appropriate type of proxy.

📅November 16, 2026

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 requests
  • HTTPS_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.