Si vous essayez de télécharger un modèle via ollama pull
depuis un réseau d'entreprise, derrière un VPN ou via un proxy externe, vous avez probablement déjà rencontré des erreurs du type
dial tcp: lookup registry.ollama.ai ou
context deadline exceeded.
Ollama ne récupère pas toujours correctement les paramètres système du proxy par défaut, et les gros poids des modèles (de 2 à 70+ Go) aggravent le problème —
la connexion se coupe au milieu du téléchargement. Dans cet article, nous allons examiner comment définir correctement les variables d'environnement, configurer le proxy dans Docker et systemd,
ainsi que déchiffrer les erreurs de pull les plus courantes et les moyens de les résoudre.
Comment Ollama fonctionne avec le réseau et le proxy
Ollama est une application client-serveur : le serveur local (ollama serve)
reçoit des commandes de l'interface en ligne de commande (CLI) et effectue des requêtes réseau vers le registre de modèles registry.ollama.ai et vers le CDN, où sont stockées les couches (layers) des modèles.
La commande ollama pull llama3 exécute en réalité une série de requêtes HTTPS,
semblables à Docker pull : d'abord, le manifeste du modèle est demandé, puis les couches binaires (fichiers GGUF de poids) sont téléchargées séquentiellement ou en parallèle.
Un point important : les requêtes réseau sont effectuées par le processus serveur Ollama, et non par la commande CLI. Cela signifie que les variables d'environnement
avec les paramètres du proxy doivent être définies là où le processus ollama serve
est exécuté, et non dans le terminal à partir duquel vous appelez ollama pull.
Si le service est lancé en tant qu'unité systemd ou dans un conteneur Docker, l'exportation de la variable dans une session bash normale n'aura aucun effet —
c'est la raison la plus courante pour laquelle "le proxy semble configuré, mais le pull ne fonctionne toujours pas".
Variables d'environnement HTTP_PROXY, HTTPS_PROXY, NO_PROXY
Ollama est écrit en Go, et la bibliothèque HTTP standard de Go lit les paramètres du proxy à partir des variables d'environnement classiques :
HTTP_PROXY— proxy pour les requêtes HTTP ordinairesHTTPS_PROXY— proxy pour les requêtes HTTPS (c'est celui-ci qui est nécessaire pour télécharger des modèles, car le registre fonctionne sur TLS)NO_PROXY— liste des hôtes à exclure du proxy (par exemple, l'API locale d'Ollama sur 127.0.0.1:11434)
Format de la valeur : http://user:password@host:port pour un proxy avec authentification
ou socks5://host:port pour SOCKS5. Go prend en charge les deux options,
mais pour SOCKS5, il est important que le binaire d'Ollama soit compilé avec le support de ce proxy — dans la plupart des versions actuelles, c'est le cas, mais en cas d'erreurs, il vaut mieux
tester d'abord sur un proxy HTTP/HTTPS pour exclure cette variable.
Important : indiquez les variables à la fois en minuscules et en majuscules
(http_proxy et HTTP_PROXY).
Certaines distributions Linux ne lisent que les minuscules, tandis que les applications Go s'attendent parfois à des majuscules — il est préférable de définir les deux variantes pour ne pas avoir de doutes.
Configuration sur Linux et macOS
Si vous exécutez Ollama directement depuis le terminal (et non en tant que service système), il suffit d'exporter les variables avant de lancer le serveur :
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
Pour que les paramètres soient conservés entre les sessions, ajoutez ces lignes à ~/.bashrc,
~/.zshrc ou ~/.profile
selon le shell utilisé. Après avoir modifié, exécutez source ~/.bashrc
et redémarrez le processus Ollama — les variables d'environnement ne sont lues qu'au démarrage du processus, le rechargement à chaud n'est pas prévu.
Sur macOS, si Ollama est installé en tant qu'application (et non via Homebrew), les variables d'environnement du terminal peuvent ne pas atteindre le processus
lancé via l'interface graphique. Dans ce cas, il est plus fiable de définir les variables via launchctl setenv :
launchctl setenv HTTPS_PROXY "http://user:[email protected]:8000"
launchctl setenv HTTP_PROXY "http://user:[email protected]:8000"
# Après cela, redémarrez complètement l'application Ollama (sortie du système de la barre d'état, pas seulement fermeture de la fenêtre)
Configuration sur Windows
Dans PowerShell, les variables sont définies pour la session actuelle avec la commande :
$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
Si Ollama est exécuté en tant que service en arrière-plan (icône dans la barre d'état système), les variables de session ne suffisent pas — le service démarre lors de la connexion au système
avant que vous n'ouvriez PowerShell. Vous devez définir les variables au niveau de l'utilisateur ou du système via
"Paramètres → Système → À propos → Paramètres système avancés → Variables d'environnement", puis terminer complètement le processus
ollama.exe via le gestionnaire des tâches et redémarrer l'application.
Proxy pour Ollama dans Docker
Si Ollama est exécuté dans un conteneur (un cas fréquent pour les déploiements serveur), les variables d'environnement de l'hôte ne sont pas automatiquement transmises à l'intérieur du conteneur —
elles doivent être explicitement transmises via -e ou la section environment
dans 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
De même dans 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:
Après avoir modifié les variables, le conteneur doit être recréé (docker compose up -d --force-recreate),
un simple redémarrage n'est pas suffisant, car les variables d'environnement sont fixées lors de la création du conteneur.
Proxy pour le service systemd Ollama
Sur les serveurs Linux, Ollama est souvent installé en tant que service systemd via le script d'installation officiel. Dans ce cas, les variables d'environnement
sont définies via un fichier d'override, et non via export dans le terminal :
sudo systemctl edit ollama.service
Dans l'éditeur qui s'ouvre, ajoutez :
[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"
Ensuite, appliquez les modifications :
sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property Environment
La dernière commande montrera quelles variables le processus voit réellement — un moyen pratique de s'assurer que la configuration a été appliquée, avant de tenter à nouveau d'exécuter un pull.
Analyse des erreurs de pull et leurs solutions
Examinons les messages d'erreur les plus courants lors du téléchargement de modèles via un proxy et ce qu'il faut en faire.
dial tcp: lookup registry.ollama.ai: no such host
La résolution DNS ne fonctionne pas derrière le proxy — cela signifie généralement que la requête essaie de passer directement, contournant le serveur proxy, ou qu'il n'y a pas d'accès
à DNS sur la machine (réseau d'entreprise fermé). Solution : assurez-vous que HTTPS_PROXY
est bien pris en compte par le processus (voir la commande systemctl show ci-dessus),
et que le serveur proxy lui-même est capable de résoudre les domaines externes (un proxy SOCKS5 résout DNS de son côté, un proxy HTTP aussi, mais certains proxys locaux ne le font pas).
proxyconnect tcp: dial tcp: connection refused
Ollama essaie de se connecter au proxy, mais reçoit un refus. Vérifiez le port et l'hôte pour des fautes de frappe, assurez-vous que le serveur proxy écoute réellement le port spécifié de l'extérieur (et pas seulement sur localhost), et que le pare-feu ne bloque pas la connexion sortante au port du proxy.
407 Proxy Authentication Required
Le proxy nécessite un nom d'utilisateur et un mot de passe, mais ils ne sont pas fournis ou sont fournis de manière incorrecte. Assurez-vous que dans la variable d'environnement, le nom d'utilisateur et le mot de passe sont intégrés dans l'URL
au format http://user:password@host:port, et que les caractères spéciaux dans le mot de passe
(comme @ ou :)
sont encodés via l'URL-encoding (%40, %3A).
x509: certificate signed by unknown authority
C'est un signe d'un proxy d'entreprise avec inspection TLS (MITM), qui remplace le certificat SSL par le sien. Le client Go d'Ollama ne fait pas confiance
à ce certificat. La solution consiste à ajouter le certificat racine d'entreprise au magasin de certificats de confiance du système
(sur Linux, généralement via update-ca-certificates après avoir copié le fichier .crt dans
/usr/local/share/ca-certificates/). Il n'est pas recommandé de désactiver la vérification des certificats globalement — cela ouvre la voie à l'interception du trafic.
context deadline exceeded / i/o timeout lors du téléchargement d'une couche
La connexion se coupe au milieu du téléchargement d'une grande couche de modèle (souvent des fichiers de 4 à 40 Go). Cette erreur indique presque toujours une instabilité ou une faible bande passante du serveur proxy, et non d'Ollama lui-même. Les proxys publics gratuits ou surchargés interrompent les longues sessions TCP, surtout si le téléchargement prend plus de quelques minutes. Dans de tels cas, il est utile de passer à un canal plus stable — par exemple, des proxys de data center, qui offrent une vitesse élevée et une connexion stable pour le téléchargement de gros fichiers sans interruptions.
Quel type de proxy choisir pour Ollama
Le choix du type de proxy dépend de la raison pour laquelle vous avez besoin d'un proxy pour Ollama. Si l'objectif est simplement de contourner les restrictions du pare-feu d'entreprise à l'intérieur de votre propre réseau, presque n'importe quel proxy HTTP(S) stable fera l'affaire. Mais si l'objectif est de contourner la géo-blocage du registre des modèles ou de masquer que la requête provient d'un data center (certains CDN limitent la vitesse pour des plages d'IP connues des fournisseurs de cloud), le choix du type de proxy devient critique.
| Type de proxy | Vitesse | Quand utiliser pour Ollama |
|---|---|---|
| Data center | Élevée | Téléchargement de grandes couches de modèles (4-40+ Go) sans interruptions, test depuis différents emplacements de centres de données |
| Résidentiels | Moyenne | Contourner les géo-restrictions du registre, lorsque l'IP du data center est soumise à un rate-limit régional |
| Mobiles | Variable | Dernier recours en cas de blocage complet par plages d'IP des fournisseurs, moins efficace pour les gros téléchargements en raison des fluctuations de vitesse |
Pour la plupart des scénarios avec Ollama — lorsque vous devez simplement télécharger de manière stable un modèle pesant des dizaines de gigaoctets — le choix optimal reste des proxys de data center : ils offrent la bande passante maximale et les latences minimales, ce qui est critique lors du téléchargement de grandes couches binaires. Les IP résidentielles ne devraient être utilisées que si les adresses des data centers sont réellement soumises à des restrictions du côté du registre des modèles.
Diagnostic de la connexion
Avant de perdre du temps à déboguer Ollama elle-même, vérifiez le proxy directement via curl — cela exclura toute confusion entre un problème dans l'application et un problème dans le serveur proxy lui-même :
# Vérification de l'accessibilité du registre via le proxy
curl -v -x http://user:[email protected]:8000 https://registry.ollama.ai/v2/
# Mesure de la vitesse de téléchargement via le proxy
curl -x http://user:[email protected]:8000 -o /dev/null -w "%{speed_download}\n" https://registry.ollama.ai/v2/
# Lancement d'ollama serve avec un log détaillé
OLLAMA_DEBUG=1 ollama serve
Si curl reçoit une réponse avec succès, mais que ollama pull échoue toujours —
le problème est presque certainement que les variables d'environnement n'ont pas été transmises au processus du serveur (le service est lancé avec un autre utilisateur, d'un autre shell
ou en tant qu'unité systemd sans override). Revenez à la section sur systemd et vérifiez la sortie de systemctl show ollama --property Environment.
Si curl échoue également lors du téléchargement d'un gros fichier ou montre une vitesse instable — la cause est du côté du serveur proxy, et il vaut la peine de considérer le changement de fournisseur de proxy pour une option plus stable, orientée vers le transfert de gros volumes de données.
Conclusion
La configuration d'Ollama derrière un proxy se résume à trois points clés : les variables d'environnement doivent être définies spécifiquement pour le processus
ollama serve, et non pour le terminal à partir duquel vous appelez le pull ;
le format de l'URL du proxy doit inclure un nom d'utilisateur et un mot de passe correctement encodés ; et en cas d'erreurs de certificats, il faut ajouter le certificat racine d'entreprise
au magasin de confiance, et non désactiver la vérification TLS. La plupart des erreurs de pull ne sont pas des bugs d'Ollama elle-même,
mais le résultat du fait que les paramètres réseau ne se sont pas appliqués au bon processus ou que le serveur proxy ne supporte pas le transfert prolongé de gros fichiers.
Si votre objectif principal est de télécharger de manière stable et rapide des modèles pesant des dizaines de gigaoctets sans interruptions de connexion, nous vous recommandons d'essayer des proxys de data center — ils offrent une bande passante élevée, nécessaire pour le téléchargement de grandes couches de modèles. Et si la raison d'utiliser un proxy est de contourner les géo-restrictions du registre des modèles, portez votre attention sur les proxys résidentiels, qui sont moins souvent soumis aux limites régionales appliquées aux plages d'IP des fournisseurs de cloud.