Introduction : pourquoi les gestionnaires de paquets ont besoin de leurs propres réglages proxy

Vous avez sûrement déjà vécu cette situation : dans le terminal, les variables http_proxy et https_proxy sont exportées, curl télécharge les pages sans problème, mais npm install se bloque pendant une minute puis échoue avec une erreur ETIMEDOUT. Ou apt update essaie silencieusement de joindre le miroir en direct, comme si aucun proxy n'existait. Ou Docker, lors de la construction d'une image, n'arrive pas à récupérer la couche de base, alors que depuis la même console docker pull fonctionne. Ce n'est ni un bug ni de la magie noire. Simplement, chaque outil a sa propre façon de lire les paramètres réseau, et les variables d'environnement ne le couvrent que partiellement.

Ce guide est consacré précisément aux fichiers de configuration propres à cinq outils dont aucun développeur ne peut se passer : npm (fichier .npmrc), pip (pip.conf ou pip.ini), apt (dossier apt.conf.d), Docker (daemon.json et config.json) et git (git config). Nous ne répétons volontairement pas le contenu sur les variables d'environnement dans le terminal et la CI. L'objectif ici est différent : montrer comment déclarer le proxy pour qu'il s'applique toujours, peu importe qui lance la commande et depuis où.

Résultat : vous obtiendrez cinq configs fonctionnelles, copiables sur n'importe quelle machine, la compréhension de l'endroit où chaque outil cherche ses réglages, et un ensemble de commandes de vérification. En plus, vous saurez comment tout annuler rapidement.

À qui s'adresse ce guide

  • Aux développeurs dont le laptop ou le serveur de travail se trouve derrière un proxy d'entreprise ou domestique.
  • Aux testeurs et spécialistes de l'automatisation qui ont besoin que les builds passent par une adresse proxy dédiée.
  • Aux administrateurs qui configurent des images types de postes de travail.
  • À tous ceux qui utilisent un proxy loué (y compris mobile) pour le développement et veulent qu'un outil précis passe par lui, et non tout le système.

Ce qu'il faut savoir au préalable

Des compétences de base en terminal suffisent : ouvrir une console, se déplacer dans un dossier, éditer un fichier texte. Nous utiliserons l'éditeur nano sous Linux et le Bloc-notes sous Windows, mais n'importe lequel fera l'affaire. Comprendre ce qu'est une adresse IP et un port sera aussi utile, même si nous rappellerons les bases dans la section sur les notions.

Combien de temps cela prendra

Si vous configurez les cinq outils à la suite, prévoyez entre 60 et 90 minutes. Chaque outil pris séparément demande 10 à 15 minutes, vérification comprise. L'étape la plus longue est Docker, car il y a deux niveaux de réglages et un redémarrage du service.

Préparation préalable

Avant de modifier les configs, rassemblons tout le nécessaire. Sauter cette étape est la première cause pour laquelle on finit par passer des heures à deviner où se trouve l'erreur.

Données nécessaires sur le proxy

Vous avez besoin de quatre paramètres. Notez-les dans un fichier texte pour ne pas avoir à les chercher dans vos messages :

  • Type de proxy : HTTP ou HTTPS (parfois SOCKS5, mais la plupart des gestionnaires de paquets attendent un proxy HTTP).
  • Adresse : nom de domaine ou IP, par exemple proxy.corp.local ou 10.20.30.40.
  • Port : le plus souvent 3128, 8080 ou 8888.
  • Login et mot de passe, si le proxy exige une authentification. Faites attention aux caractères spéciaux dans le mot de passe : ils nécessiteront un encodage, on en parle plus bas.

Configuration requise et versions

L'instruction a été testée sur les versions actuelles de 2026 et convient pour :

  • Ubuntu 22.04 et 24.04, Debian 12 et 13 (pour apt).
  • Node.js 20 et 22 avec npm 10 et 11.
  • Python 3.10 et plus récent avec pip 24 et plus récent.
  • Docker Engine 25 et plus récent (la clé proxies dans daemon.json est apparue en version 23 ; sur les versions plus anciennes, utilisez un drop-in systemd, nous montrerons les deux variantes).
  • Git 2.40 et plus récent.

Si vous êtes sous Windows, toutes les commandes pour npm, pip et git fonctionnent dans PowerShell sans modification, seuls les chemins de fichiers diffèrent. Pour Docker Desktop, les réglages proxy se font via l'interface graphique, nous verrons cela aussi.

Droits d'accès

Pour npm, pip et git, les droits d'un utilisateur ordinaire suffisent : leurs configs se trouvent dans le répertoire personnel. Pour apt et Docker, sudo sera nécessaire, car les fichiers sont dans /etc et modifient le comportement des services système.

Sauvegardes

Avant de commencer, copiez les configs existantes. Une commande par fichier, et vous pourrez toujours revenir à l'état initial :

cp ~/.npmrc ~/.npmrc.bak 2>/dev/null; cp ~/.config/pip/pip.conf ~/pip.conf.bak 2>/dev/null; cp ~/.gitconfig ~/.gitconfig.bak 2>/dev/null; sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak 2>/dev/null; sudo cp -r /etc/apt/apt.conf.d /etc/apt/apt.conf.d.bak 2>/dev/null

Le suffixe 2>/dev/null sert à éviter que la commande râle si le fichier n'existe pas encore. C'est normal : chez beaucoup d'utilisateurs, .npmrc et pip.conf sont absents au départ.

Conseil : créez dans votre répertoire personnel un dossier proxy-configs et gardez-y les versions de référence des cinq configs. Déménager sur une nouvelle machine se résumera à copier cinq fichiers.

Notions de base : pourquoi les variables d'environnement ne suffisent pas

Comprenons ce qui se passe sous le capot, sinon les étapes suivantes ressembleront à une série de formules magiques.

Qu'est-ce qu'un proxy dans le contexte d'un gestionnaire de paquets

Un serveur proxy est un intermédiaire. Au lieu de se connecter directement à registry.npmjs.org, votre npm se connecte au proxy et lui demande d'aller sur registry.npmjs.org. Pour les ressources HTTPS, on utilise la méthode CONNECT : le proxy établit un tunnel, et le trafic chiffré le traverse sans être déchiffré. Pour le gestionnaire de paquets, l'essentiel est de connaître l'adresse du proxy, le port et, si nécessaire, les identifiants.

Comment les outils prennent connaissance du proxy

Il existe trois couches de réglages, et elles forment une chaîne de priorités :

  1. Les options de ligne de commande : par exemple, pip install --proxy. Valables pour un seul lancement.
  2. La config propre à l'outil : .npmrc, pip.conf et autres. Valables toujours pour cet outil.
  3. Les variables d'environnement : http_proxy, https_proxy, no_proxy. Valables pour tous les programmes de la session en cours qui les lisent.

Le mot clé est qui les lisent. Et c'est là que les problèmes commencent.

Quatre raisons pour lesquelles les variables d'environnement ne suffisent pas

Première raison : le changement d'utilisateur. Quand vous tapez sudo apt update, la commande s'exécute en tant que root, et sudo nettoie par défaut l'environnement (option env_reset). Vos http_proxy restent attachés à l'utilisateur ordinaire. De plus, apt lui-même télécharge les fichiers sous l'utilisateur de service _apt, qui n'a aucune de vos sessions.

Deuxième raison : les démons et les services. Docker Engine est un service d'arrière-plan lancé par systemd au démarrage du système. Il n'a jamais vu votre terminal. La commande docker pull ne fait qu'envoyer une requête au démon, et c'est le démon qui télécharge l'image. Donc les variables de votre console n'ont aucun effet sur docker pull.

Troisième raison : les interprétations divergentes. Certains programmes ne lisent que http_proxy en minuscules, d'autres seulement HTTP_PROXY, d'autres les deux. Les anciennes versions de npm ignoraient no_proxy. Certains outils ne comprennent pas les identifiants dans la variable. La config propre à l'outil évite de devoir deviner.

Quatrième raison : la granularité. Une variable d'environnement est soit présente, soit absente. Or vous pouvez avoir besoin de faire passer uniquement github.com par le proxy, mais pas le GitLab interne. Ou d'aller sur PyPI public via le proxy, mais sur l'index interne en direct. Seules les configs savent faire cela : git gère un proxy par URL spécifique, apt par hôte spécifique, Docker une liste d'exclusions au niveau du démon.

Encodage des caractères spéciaux dans le mot de passe

Le login et le mot de passe dans les configs sont transmis à l'intérieur d'une URL du type http://user:password@host:port. Les caractères @, :, /, #, ?, % et l'espace à l'intérieur du mot de passe cassent l'analyse de l'adresse. Il faut les remplacer par des codes pour cent : @ devient %40, : devient %3A, # devient %23, / devient %2F, % devient %25, l'espace devient %20. Par exemple, le mot de passe p@ss:1 s'écrira p%40ss%3A1 dans la config. Retenez cette règle, elle vous sauvera dans les cinq outils.

Étape 1 : vérifier le proxy et préparer la chaîne de référence

Objectif de l'étape : s'assurer que le proxy fonctionne, et obtenir une chaîne de connexion vérifiée que nous insérerons dans toutes les configs.

  1. Ouvrez un terminal. Sous Linux, c'est Ctrl+Alt+T ; sous Windows, PowerShell depuis le menu Démarrer.
  2. Composez la chaîne de connexion selon le modèle http://LOGIN:MOT_DE_PASSE@ADRESSE:PORT. Sans authentification, simplement http://ADRESSE:PORT. Exemple : http://dev:s3cret@10.20.30.40:3128.
  3. Lancez une requête test via curl, en précisant le proxy avec l'option -x, pour ne pas dépendre des variables :
    curl -x http://dev:s3cret@10.20.30.40:3128 -I https://registry.npmjs.org/
  4. Attendez la réponse. Elle doit commencer par HTTP/2 200 ou HTTP/1.1 200 OK. Si vous voyez 407 Proxy Authentication Required, le login ou le mot de passe est incorrect. Si c'est Could not resolve proxy, il y a une faute de frappe dans l'adresse. Si c'est connection refused, le port est mauvais ou le proxy est éteint.
  5. Répétez la vérification pour les autres cibles : https://pypi.org/simple/, https://deb.debian.org/, https://registry-1.docker.io/v2/, https://github.com/. Pour Docker, une réponse 401 est normale : cela signifie que vous avez atteint le registre et qu'il demande un token.
  6. Notez la chaîne finale dans votre fichier texte. C'est votre chaîne de référence du proxy.

Attention : si le mot de passe contient des caractères spéciaux, encodez-les dès cette étape et vérifiez la version encodée via curl. Ainsi, dans toutes les configs suivantes, vous insérerez une chaîne déjà éprouvée.

Conseil : si votre fournisseur vous donne non pas un seul proxy, mais un pool d'adresses ou un proxy mobile à rotation d'IP, il dispose en général d'un point d'entrée unique : un seul hôte et port, derrière lequel les IP changent automatiquement. Déclarez dans les configs précisément ce point d'entrée, et non des IP concrètes du pool, sinon les réglages deviendront obsolètes dès la première rotation.

Vérification : curl avec l'option -x renvoie le code 200 (ou 401 pour Docker Hub) sur les cinq adresses. Si au moins une ne répond pas, n'allez pas plus loin : les configs ne répareront pas un proxy défaillant.

Étape 2 : configurer npm via le fichier .npmrc

Objectif de l'étape : que npm install, npm view et npm publish fonctionnent via le proxy depuis n'importe quel projet et n'importe quelle console, y compris les environnements de développement qui lancent npm eux-mêmes.

Où se trouve la config npm

npm lit ses réglages dans plusieurs fichiers par ordre de priorité croissante : valeurs intégrées, fichier global dans le répertoire d'installation de npm, fichier utilisateur ~/.npmrc (sous Windows, C:\Users\NOM\.npmrc) et .npmrc de projet à la racine du projet à côté de package.json. Pour le proxy, on utilise presque toujours le fichier utilisateur : il s'applique à tous les projets, mais n'entre pas dans le dépôt.

Configuration pas à pas

  1. Définissez le proxy pour le trafic HTTP ordinaire :
    npm config set proxy http://dev:s3cret@10.20.30.40:3128
  2. Définissez le proxy pour le trafic HTTPS (le registre npm fonctionne en HTTPS, donc ce réglage est le principal) :
    npm config set https-proxy http://dev:s3cret@10.20.30.40:3128
    Attention : la valeur commence par http://, et non https://. C'est l'adresse du proxy lui-même, et celui-ci accepte généralement les connexions en HTTP simple, même lorsqu'il tunnelise du HTTPS.
  3. Si vous avez un registre interne ou un miroir auquel il faut accéder directement, ajoutez les exclusions séparées par des virgules :
    npm config set noproxy localhost,127.0.0.1,.corp.local
    Le point devant le domaine signifie tous les sous-domaines.
  4. Ouvrez le fichier et vérifiez que les lignes ont bien été écrites :
    cat ~/.npmrc
    Sous Windows : type $env:USERPROFILE\.npmrc. Vous devez voir trois lignes du type clé=valeur.
  5. Si le proxy d'entreprise remplace les certificats, ajoutez le certificat racine de l'entreprise :
    npm config set cafile /etc/ssl/certs/corp-root.pem
    Ne désactivez pas la vérification des certificats via strict-ssl=false sans nécessité absolue : cela ouvre la voie à la substitution de paquets.

Autre possibilité : créer le fichier manuellement. Le contenu de ~/.npmrc sera le suivant :

proxy=http://dev:s3cret@10.20.30.40:3128 https-proxy=http://dev:s3cret@10.20.30.40:3128 noproxy=localhost,127.0.0.1,.corp.local

Chaque paire doit être sur une ligne séparée. Sans guillemets ni espaces autour du signe égal.

Et yarn et pnpm ?

Yarn Classic (1.x) lit le même ~/.npmrc et en plus son propre ~/.yarnrc avec les clés proxy et https-proxy. Yarn Berry (2+) stocke ses réglages dans .yarnrc.yml : clés httpProxy et httpsProxy. pnpm est totalement compatible avec .npmrc, rien de plus à faire. Il faut aussi garder en tête que npm ci et les IDE d'entreprise lancent npm sous le même utilisateur, donc le .npmrc utilisateur les couvre aussi.

Conseil : la commande npm config list --json affiche la configuration finale en tenant compte de tous les fichiers. Si vous voyez proxy=null, c'est que le fichier n'a pas été lu : vérifiez qu'il se trouve bien dans le répertoire personnel de l'utilisateur sous lequel vous lancez npm.

Vérification : lancez npm view lodash version. Au bout de 1 à 3 secondes, une ligne avec le numéro de version doit revenir. Pour être plus clair, vous pouvez temporairement retirer les variables d'environnement (unset http_proxy https_proxy) et répéter : npm doit quand même fonctionner, car il lit .npmrc.

Problèmes possibles

  • ETIMEDOUT ou ECONNRESET : adresse ou port de proxy incorrect, ou proxy qui bloque CONNECT sur le port 443. Vérifiez la chaîne de référence via curl.
  • 407 Proxy Authentication Required : erreur de login ou de mot de passe, le plus souvent un caractère spécial non encodé.
  • UNABLE_TO_GET_ISSUER_CERT_LOCALLY : le proxy remplace le certificat, il faut un cafile avec le certificat racine de l'entreprise.

Étape 3 : configurer pip via pip.conf

Objectif de l'étape : que pip install et pip download fonctionnent via le proxy, y compris à l'intérieur d'environnements virtuels et lors de lancements depuis des scripts Python.

Où chercher pip.conf

pip utilise trois niveaux de fichiers : global (pour tout le système), utilisateur et niveau environnement virtuel. Les chemins dépendent du système :

  • Linux, utilisateur : ~/.config/pip/pip.conf (l'ancienne variante ~/.pip/pip.conf est aussi lue).
  • Linux, global : /etc/pip.conf.
  • macOS, utilisateur : ~/Library/Application Support/pip/pip.conf, et si ce dossier n'existe pas : ~/.config/pip/pip.conf.
  • Windows, utilisateur : %APPDATA%\pip\pip.ini, c'est-à-dire C:\Users\NOM\AppData\Roaming\pip\pip.ini.
  • À l'intérieur d'un environnement virtuel : le fichier pip.conf (ou pip.ini) directement à la racine du dossier venv.

Pour ne pas avoir à deviner, interrogez pip lui-même : la commande pip config debug affiche tous les chemins qu'il vérifie et marque les fichiers existants.

Configuration pas à pas

  1. Assurez-vous que pip est à jour : pip --version. La version doit être 24 ou plus récente.
  2. Définissez le proxy en une commande, pip créera lui-même le fichier au bon endroit :
    pip config set global.proxy http://dev:s3cret@10.20.30.40:3128
    Ici global désigne la section [global] du fichier, pas le niveau système. Le fichier créé est celui de l'utilisateur.
  3. Si le proxy remplace les certificats, indiquez le certificat racine :
    pip config set global.cert /etc/ssl/certs/corp-root.pem
  4. Regardez ce que cela donne :
    pip config list
    Sortie attendue : global.proxy='http://dev:s3cret@10.20.30.40:3128'.
  5. Ouvrez le fichier et vérifiez le format. Il doit ressembler à ceci :
    [global] proxy = http://dev:s3cret@10.20.30.40:3128 cert = /etc/ssl/certs/corp-root.pem
    Chaque ligne séparément, la section entre crochets en haut.

Différence importante entre pip et npm : pip n'a pas de réglage distinct pour le proxy HTTPS. Une seule clé proxy est utilisée pour toutes les connexions. Et pip n'a pas d'équivalent direct à noproxy dans sa config : il ne prend les exclusions que dans la variable d'environnement no_proxy. Si vous avez besoin d'aller directement sur un index interne, le plus simple est de lui indiquer un index-url séparé et de lancer pip avec un --proxy vide pour ce cas, ou d'utiliser un pip.conf de projet dans le venv sans la ligne proxy.

Conseil : si vous avez plusieurs projets et que l'un a besoin du proxy et l'autre non, placez le pip.conf à la racine de l'environnement virtuel correspondant. Les réglages du venv ont priorité sur ceux de l'utilisateur, et vous obtiendrez des comportements différents sans avoir à basculer les fichiers globaux.

Attention : n'ajoutez pas trusted-host = pypi.org pour masquer les erreurs de certificat. Cela désactive la vérification d'authenticité et permet à n'importe quel intermédiaire de vous glisser un faux paquet. La bonne solution est la clé cert avec le certificat d'entreprise.

Vérification : lancez pip download requests --no-deps -d /tmp/piptest. Au bout de quelques secondes, un fichier requests-*.whl apparaîtra dans le dossier. Supprimez ensuite le dossier de test. Si vous voulez vous assurer que c'est bien la config qui agit, retirez les variables d'environnement et répétez.

Problèmes possibles

  • ProxyError ou Cannot connect to proxy : faute de frappe dans l'adresse ou port incorrect. Comparez avec la chaîne de référence.
  • Tunnel connection failed: 407 : erreur d'authentification. Vérifiez l'encodage du mot de passe.
  • SSLError CERTIFICATE_VERIFY_FAILED : il faut la clé cert avec le certificat racine du proxy.
  • Le fichier a été écrit, mais pip ne le voit pas : vous lancez le pip d'un autre interpréteur (par exemple python3 -m pip d'un autre Python). Lancez pip config debug exactement avec la commande qui sert à installer les paquets.

Étape 4 : configurer apt via le dossier apt.conf.d

Objectif de l'étape : que sudo apt update et sudo apt install téléchargent les paquets via le proxy, tandis que les requêtes vers le miroir interne passent en direct.

Pourquoi précisément apt.conf.d

apt lit ses réglages dans /etc/apt/apt.conf et dans tous les fichiers du dossier /etc/apt/apt.conf.d/ par ordre alphabétique. La bonne pratique est de ne pas toucher aux fichiers des autres, mais de créer le sien avec un préfixe numérique. Le nombre détermine l'ordre de lecture : le fichier 80proxy s'appliquera après 01autoremove et les autres fichiers système. C'est ici que les réglages survivront à toutes les mises à jour du paquet apt.

Configuration pas à pas

  1. Créez un nouveau fichier de configuration :
    sudo nano /etc/apt/apt.conf.d/80proxy
    Un éditeur vide s'ouvrira.
  2. Écrivez deux lignes pour les dépôts HTTP et HTTPS. Faites attention aux guillemets et aux points-virgules, ils sont obligatoires dans la syntaxe apt :
    Acquire::http::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::https::Proxy "http://dev:s3cret@10.20.30.40:3128";
  3. S'il y a un miroir interne qui n'a pas besoin du proxy, ajoutez une ligne d'exclusion. Le mot DIRECT en majuscules signifie connexion directe :
    Acquire::http::Proxy::mirror.corp.local "DIRECT";
  4. Enregistrez le fichier : dans nano, appuyez sur Ctrl+O, puis Entrée, puis Ctrl+X pour quitter.
  5. Limitez les droits sur le fichier, car il contient le mot de passe :
    sudo chmod 600 /etc/apt/apt.conf.d/80proxy
    Seul root pourra en lire le contenu.
  6. Vérifiez qu'apt a analysé le fichier sans erreur de syntaxe :
    apt-config dump | grep -i proxy
    Vous devez voir les lignes Acquire::http::Proxy et Acquire::https::Proxy avec vos valeurs.

Voici un exemple complet de fichier pour bien visualiser :

Acquire::http::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::https::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::http::Proxy::mirror.corp.local "DIRECT"; Acquire::https::Proxy::mirror.corp.local "DIRECT";

Alternative pour un seul lancement sans fichier : sudo apt -o Acquire::http::Proxy="http://10.20.30.40:3128" update. L'option -o est pratique pour tester une valeur avant de l'écrire dans la config.

Conseil : les serveurs proxy qui cachent eux-mêmes les paquets deb ont souvent un port dédié pour apt. Renseignez-vous auprès de l'administrateur : s'il en existe un, apt update s'accélérera plusieurs fois grâce au cache local.

Vérification : lancez sudo apt update. Dans la sortie, des lignes Hit ou Get avec les adresses des dépôts apparaîtront, et il n'y aura pas de lignes Err. Notez que nous n'avons pas défini de variables d'environnement, et que sudo les aurait de toute façon effacées : apt est quand même sorti sur le réseau. C'est justement l'effet de la config propre à l'outil.

Problèmes possibles

  • Err: 407 Proxy Authentication Required : l'authentification n'a pas abouti, vérifiez l'encodage des caractères spéciaux.
  • Could not connect ou Connection timed out : apt est passé en direct. Il y a probablement une faute de frappe dans le fichier, que apt-config dump ne montre pas. Vérifiez la casse dans Acquire et les doubles deux-points.
  • E: Syntax error : un point-virgule ou un guillemet manque en fin de ligne.
  • Le fichier est bien là, mais l'exclusion DIRECT ne fonctionne pas : assurez-vous que le nom d'hôte dans la ligne d'exclusion correspond exactement à celui de sources.list, sans http:// ni port.

Étape 5 : configurer Docker sur deux niveaux

Objectif de l'étape : que docker pull, docker build et docker compose pull téléchargent les images via le proxy, et que les conteneurs reçoivent automatiquement les réglages proxy si nécessaire.

Deux niveaux souvent confondus

Docker a deux endroits indépendants où le proxy est nécessaire de façon différente :

  • Le niveau démon (service dockerd). C'est lui qui télécharge les images depuis le registre. Se configure dans /etc/docker/daemon.json ou via systemd. Nécessite un redémarrage du service.
  • Le niveau client (fichier ~/.docker/config.json). Il n'influence pas le téléchargement des images. En revanche, il transmet automatiquement les variables de proxy à l'intérieur des conteneurs lancés et au processus de build, pour qu'apt ou pip dans le conteneur voient eux aussi le proxy.

Si vous ne configurez que le client, docker pull ne marchera pas. Si vous ne configurez que le démon, les images se téléchargent, mais RUN apt-get update dans le Dockerfile échouera. Il faut les deux.

Partie A : le démon via daemon.json

  1. Vérifiez la version : docker version. Si la version du serveur est 23.0 ou plus récente, utilisez daemon.json. Si elle est plus ancienne, passez à la partie B.
  2. Ouvrez le fichier de configuration du démon :
    sudo nano /etc/docker/daemon.json
    Si le fichier existe déjà et contient d'autres clés, ajoutez le bloc proxies à l'intérieur des mêmes accolades, séparé par une virgule. Si le fichier n'existe pas, créez-le de zéro.
  3. Écrivez le bloc de réglages :
    { "proxies": { "http-proxy": "http://dev:s3cret@10.20.30.40:3128", "https-proxy": "http://dev:s3cret@10.20.30.40:3128", "no-proxy": "localhost,127.0.0.0/8,registry.corp.local" } }
    Attention : les clés s'écrivent avec des tirets et en minuscules, exactement comme cela. C'est le format du démon ; chez le client, les clés seront différentes.
  4. Enregistrez le fichier (Ctrl+O, Entrée, Ctrl+X).
  5. Vérifiez que le JSON est valide, sinon le démon ne démarrera pas :
    python3 -m json.tool /etc/docker/daemon.json
    Si la commande a affiché le contenu du fichier avec des indentations, la syntaxe est correcte. Si elle râle avec Expecting value ou Extra data, cherchez une virgule en trop ou manquante.
  6. Redémarrez le service :
    sudo systemctl restart docker
    Le redémarrage prendra 5 à 15 secondes. Tous les conteneurs en cours seront arrêtés, donc faites-le à un moment calme.
  7. Assurez-vous que le démon est bien remonté : sudo systemctl status docker. La mention active (running) doit apparaître en vert.

Attention : une virgule en trop dans daemon.json et Docker ne démarre pas du tout, entraînant avec lui tous les conteneurs de la machine. Vérifiez toujours le fichier avec json.tool avant de redémarrer et gardez une sauvegarde à portée de main.

Partie B : le démon via systemd (pour les anciennes versions et comme alternative)

  1. Créez le dossier pour les réglages supplémentaires du service : sudo mkdir -p /etc/systemd/system/docker.service.d
  2. Créez le fichier : sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf
  3. Écrivez :
    [Service] Environment="HTTP_PROXY=http://dev:s3cret@10.20.30.40:3128" Environment="HTTPS_PROXY=http://dev:s3cret@10.20.30.40:3128" Environment="NO_PROXY=localhost,127.0.0.0/8,registry.corp.local"
  4. Enregistrez et appliquez : sudo systemctl daemon-reload, puis sudo systemctl restart docker.

Oui, on utilise ici des variables d'environnement, mais elles ne sont pas définies dans votre console : elles le sont dans la définition du service, et le démon les reçoit au démarrage de systemd. C'est la seule méthode pour Docker antérieur à la version 23. Si vous avez à la fois daemon.json et le fichier systemd, la priorité va à daemon.json.

Partie C : le client via ~/.docker/config.json

  1. Ouvrez ou créez le fichier nano ~/.docker/config.json. Si le fichier contient déjà un bloc auths avec vos logins aux registres, ne le supprimez pas, ajoutez un nouveau bloc à côté, séparé par une virgule.
  2. Écrivez :
    { "proxies": { "default": { "httpProxy": "http://dev:s3cret@10.20.30.40:3128", "httpsProxy": "http://dev:s3cret@10.20.30.40:3128", "noProxy": "localhost,127.0.0.0/8,.corp.local" } } }
    Ici les clés sont en style camelCase : httpProxy, httpsProxy, noProxy. C'est la différence avec daemon.json, et il ne faut pas les confondre.
  3. Enregistrez le fichier. Aucun redémarrage n'est nécessaire, le client le lit à chaque commande.

Désormais, lors de docker run et docker build, les variables HTTP_PROXY, HTTPS_PROXY et NO_PROXY (dans les deux casses) seront automatiquement transmises au conteneur. Cela signifie qu'apt-get et pip dans le Dockerfile passeront eux aussi par le proxy sans ARG ni ENV manuels.

Docker Desktop sous Windows et macOS

Ouvrez les réglages via l'icône dans la zone de notification, section Resources, sous-section Proxies. Activez Manual proxy configuration, saisissez l'adresse dans les champs Web Server (HTTP) et Secure Web Server (HTTPS), et la liste d'exceptions dans Bypass proxy settings for these hosts and domains. Cliquez sur Apply and restart. Le config.json client sous Windows se trouve dans C:\Users\NOM\.docker\config.json et se configure comme décrit plus haut.

Conseil : la commande docker info affiche une section avec HTTP Proxy, HTTPS Proxy et No Proxy. C'est le moyen le plus rapide de savoir si le démon a bien vu vos réglages, sans lancer de téléchargement.

Vérification : lancez docker pull hello-world. L'image pèse quelques kilo-octets et se téléchargera en quelques secondes, avec Status: Downloaded newer image à la fin. Vérifiez ensuite la partie client : docker run --rm alpine env | grep -i proxy. La sortie doit contenir les lignes HTTP_PROXY et HTTPS_PROXY avec votre adresse.

Problèmes possibles

  • Docker ne démarre pas après modification de daemon.json : erreur de syntaxe. Regardez sudo journalctl -u docker -n 30, la ligne fautive y sera indiquée. Restaurez depuis la sauvegarde.
  • docker pull se bloque puis échoue en timeout, alors que docker info affiche le proxy : le démon n'a pas été redémarré après modification, ou le proxy ne laisse pas passer CONNECT vers registry-1.docker.io. Vérifiez la chaîne de référence via curl.
  • Dans le build, apt-get update échoue, alors que docker pull fonctionne : le config.json client n'est pas configuré, ou le build passe par un builder distant qui lit un autre fichier.
  • Le conteneur a reçu le proxy, mais n'arrive pas à joindre un conteneur voisin : ajoutez les noms des services internes et le sous-réseau Docker dans noProxy.

Étape 6 : configurer git via git config

Objectif de l'étape : que git clone, fetch, pull et push via HTTPS passent par le proxy, tout en laissant l'accès direct au serveur interne et en permettant de définir un proxy séparé pour un hébergement précis.

Où git stocke ses réglages

Trois niveaux : système (/etc/gitconfig), global pour l'utilisateur (~/.gitconfig, sous Windows C:\Users\NOM\.gitconfig) et local dans le dépôt (.git/config). Le proxy est généralement défini globalement, et les exceptions ciblées aussi, mais avec un rattachement à l'URL.

Configuration pas à pas

  1. Définissez le proxy pour toutes les connexions HTTPS et HTTP en une commande :
    git config --global http.proxy http://dev:s3cret@10.20.30.40:3128
    Contrairement à npm, git n'a pas de https.proxy distinct pour le protocole HTTPS : la clé http.proxy s'applique aux deux. Le réglage https.proxy apparaît dans de vieux tutoriels, mais ce n'est pas une clé standard de git et elle est ignorée.
  2. Si le proxy n'est pas nécessaire pour le serveur interne, définissez une valeur vide uniquement pour son URL :
    git config --global http.https://git.corp.local.proxy ""
    La chaîne vide signifie connexion directe. La partie entre http. et .proxy est le préfixe d'URL auquel la règle s'applique.
  3. Si un hébergement précis a besoin d'un autre proxy (par exemple un proxy mobile dédié), indiquez-le de la même manière avec rattachement à l'URL :
    git config --global http.https://github.com.proxy http://dev:s3cret@10.20.30.41:3128
  4. Si le proxy remplace les certificats, ajoutez le certificat racine :
    git config --global http.sslCAInfo /etc/ssl/certs/corp-root.pem
  5. Vérifiez le fichier final :
    git config --global --list | grep -i proxy
    Vous verrez les lignes http.proxy=... et http.https://git.corp.local.proxy= avec une valeur vide.

Le fichier ~/.gitconfig après ces commandes ressemblera à ceci :

[http] proxy = http://dev:s3cret@10.20.30.40:3128 sslCAInfo = /etc/ssl/certs/corp-root.pem [http "https://git.corp.local"] proxy = [http "https://github.com"] proxy = http://dev:s3cret@10.20.30.41:3128

Une telle granularité est inatteignable via les variables d'environnement : no_proxy ne sait qu'exclure des hôtes, mais pas attribuer différents proxys à différents serveurs.

Et les adresses SSH ?

Le réglage http.proxy n'influence pas les adresses du type git@github.com:user/repo.git, car c'est le protocole SSH, pas HTTP. Si votre proxy autorise le tunnellisation vers le port 22 via CONNECT, on peut configurer le client SSH dans ~/.ssh/config avec la directive ProxyCommand et un utilitaire nc ou corkscrew. Mais beaucoup de proxys d'entreprise interdisent ces connexions. La voie la plus simple et la plus prévisible est de basculer les adresses distantes en HTTPS : git remote set-url origin https://github.com/user/repo.git, et d'utiliser un token d'accès à la place du mot de passe.

Conseil : pour ne pas stocker le mot de passe du proxy en clair dans ~/.gitconfig, vous pouvez le placer dans un fichier séparé avec des droits 600 et le rattacher via la directive include. Créez ~/.gitconfig-proxy avec une section [http], et dans le fichier principal, ajoutez [include] path = ~/.gitconfig-proxy. La config principale peut alors être montrée à vos collègues sans souci.

Vérification : lancez git ls-remote https://github.com/git/git.git HEAD. Au bout de quelques secondes, une ligne avec le hash du commit et le mot HEAD reviendra. La commande ne crée aucun fichier et ne clone rien, c'est le test idéal de la partie réseau. Vérifiez ensuite l'exclusion : git ls-remote vers le serveur interne doit fonctionner même avec un proxy indisponible.

Problèmes possibles

  • Failed to connect to proxy ou Could not resolve proxy : faute de frappe dans l'adresse.
  • Received HTTP code 407 from proxy after CONNECT : erreur d'authentification, vérifiez l'encodage du mot de passe.
  • SSL certificate problem: unable to get local issuer certificate : il faut http.sslCAInfo. N'utilisez pas http.sslVerify false de façon permanente.
  • La règle pour l'URL ne s'applique pas : le préfixe doit correspondre au début de l'adresse dans le remote. Si le remote est écrit https://www.github.com, la règle pour https://github.com ne fonctionnera pas.

Vérification du résultat : checklist récapitulative

Après avoir configuré les cinq outils, passez la vérification finale. Elle est volontairement construite pour exclure l'influence des variables d'environnement et s'assurer que ce sont bien les configs qui agissent.

  1. Ouvrez un nouveau terminal et retirez les variables si elles sont définies : unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY. Dans PowerShell : Remove-Item Env:HTTP_PROXY et de même pour les autres.
  2. Vérifiez npm : npm view express version. Un numéro de version est attendu.
  3. Vérifiez pip : pip download six --no-deps -d /tmp/t. Un fichier whl téléchargé est attendu.
  4. Vérifiez apt : sudo apt update. Des lignes Hit ou Get sans Err sont attendues.
  5. Vérifiez Docker : docker pull hello-world et docker run --rm alpine env | grep -i proxy. Une image téléchargée et des variables dans le conteneur sont attendues.
  6. Vérifiez git : git ls-remote https://github.com/git/git.git HEAD. Un hash de commit est attendu.

Indicateurs de réussite

  • Les six commandes ont fonctionné sans variables d'environnement dans la console.
  • Dans les fichiers .npmrc, pip.conf, 80proxy, daemon.json, config.json et .gitconfig, la même chaîne de référence du proxy est inscrite.
  • Les fichiers contenant des mots de passe (80proxy, daemon.json, .npmrc, pip.conf, .gitconfig) ont des droits 600 ou ne sont accessibles qu'à root.
  • Les exclusions pour les hôtes internes fonctionnent : y accéder passe même quand le proxy est éteint.
  • Les sauvegardes des fichiers d'origine sont à côté et vous savez comment les restaurer.

Vérification : si au moins un point n'est pas respecté, revenez à la section de l'outil concerné et comparez votre fichier avec l'exemple du guide symbole par symbole. Dans neuf cas sur dix, la cause est une faute de frappe ou un caractère non encodé dans le mot de passe.

Erreurs typiques et solutions

Erreur 1 : code 407 Proxy Authentication Required partout

Cause : le mot de passe contient un caractère spécial (@, :, #, %) qui n'a pas été encodé, et l'outil a mal analysé l'adresse.

Solution : encodez les caractères en codes pour cent (@ en %40, : en %3A, # en %23, % en %25) et vérifiez la nouvelle chaîne via curl -x avant de l'écrire dans les configs.

Erreur 2 : ça marche depuis le terminal, pas via sudo

Cause : sudo efface l'environnement, et vous n'avez pas encore créé la config. Classique pour apt.

Solution : créez /etc/apt/apt.conf.d/80proxy comme à l'étape 4. Pour les autres outils sous root, rappelez-vous que root lit son propre répertoire personnel /root, pas le vôtre : si vous avez besoin de npm ou pip en root, la config doit être dans /root/.npmrc ou /root/.config/pip/pip.conf.

Erreur 3 : Docker ne démarre pas après modification de daemon.json

Cause : JSON invalide : virgule en trop après le dernier élément, accolade manquante, guillemets simples au lieu de doubles.

Solution : lancez sudo journalctl -u docker -n 30, trouvez la ligne de l'erreur, corrigez le fichier et vérifiez-le avec python3 -m json.tool avant le prochain redémarrage. En dernier recours, restaurez daemon.json.bak.

Erreur 4 : docker pull fonctionne, mais apt-get dans le Dockerfile échoue

Cause : le démon est configuré, mais pas le client. Les processus dans le conteneur n'héritent pas des réglages du démon.

Solution : créez ~/.docker/config.json avec le bloc proxies.default comme dans la partie C de l'étape 5. Après cela, docker build transmettra automatiquement les variables aux étapes RUN.

Erreur 5 : erreurs de certificat SSL dans tous les outils

Cause : le proxy inspecte le trafic et présente son propre certificat, auquel le système ne fait pas confiance.

Solution : récupérez auprès de l'administrateur le certificat racine du proxy au format PEM et déclarez-le : npm cafile, pip cert, git http.sslCAInfo. Pour apt et Docker, il suffit d'ajouter le certificat au magasin système : copiez-le dans /usr/local/share/ca-certificates/ et lancez sudo update-ca-certificates, puis redémarrez Docker. Ne désactivez pas la vérification des certificats avec les options strict-ssl, trusted-host et sslVerify.

Erreur 6 : pip ignore pip.conf

Cause : la machine a plusieurs versions de Python, et vous modifiez la config de l'une alors que vous en lancez une autre. Ou le fichier se trouve à un emplacement obsolète que la version concernée ne lit pas.

Solution : lancez python3 -m pip config debug avec la même commande que celle qui installe les paquets. La sortie montrera quels fichiers ont été trouvés. Déplacez les réglages vers le chemin utilisateur trouvé.

Erreur 7 : git passe par le proxy même vers le serveur interne

Cause : la règle d'exclusion est définie pour une URL qui ne correspond pas à l'adresse dans le remote. Ou elle est définie dans le .git/config local d'un autre dépôt.

Solution : regardez l'adresse exacte via git remote -v, copiez son début jusqu'au nom d'hôte, et définissez la règle http.URL_EXACTE.proxy avec une valeur vide via --global.

Erreur 8 : tout marchait, et après un changement de mot de passe proxy tout casse

Cause : le mot de passe est inscrit dans cinq fichiers différents, vous n'avez pas tout mis à jour.

Solution : utilisez la commande grep -rl 'ancien_mot_de_passe' ~/.npmrc ~/.config/pip ~/.gitconfig ~/.docker et sudo grep -rl pour /etc/apt/apt.conf.d et /etc/docker, pour trouver toutes les occurrences, et mettez à jour chacune. Puis relancez la checklist récapitulative.

Fonctionnalités complémentaires

Un proxy local agrégateur comme point d'entrée unique

Si les identifiants du proxy changent souvent ou si le pool d'adresses tourne, il est pratique de faire tourner sur sa machine un proxy local léger (par exemple sur 127.0.0.1:3128), qui sait lui-même où aller et avec quels identifiants. On inscrit alors dans les cinq configs une seule adresse sans mot de passe, et le changement de coordonnées se fait à un seul endroit. Cela résout aussi le problème des outils qui gèrent mal l'authentification dans l'URL.

Miroirs et proxys cacheurs pour les paquets

Un proxy n'est pas obligé d'être universel. Pour apt, il existe des proxys cacheurs qui stockent les fichiers deb localement et les servent à tout le bureau. Pour npm et pip, les entreprises installent des registres privés qui proxifient les dépôts publics et les mettent en cache au passage. Dans ce cas, au lieu de la clé proxy, on utilise registry dans .npmrc et index-url dans pip.conf, et le proxy vers le monde extérieur se configure sur ce registre. Pour Docker, le rôle équivalent est joué par la clé registry-mirrors dans daemon.json.

Réglages séparés pour différents projets

Le .npmrc de projet à côté de package.json, le pip.conf dans le venv et le .git/config local permettent à un projet de passer par le proxy et à un autre d'aller en direct. Attention à ne pas committer les fichiers avec mots de passe dans le dépôt : ajoutez-les à .gitignore ou utilisez des variables de substitution du type ${PROXY_URL}, que npm sait étendre depuis l'environnement à la lecture de .npmrc.

Automatisation du déploiement

Les cinq configs sont de simples fichiers texte. Ils se déploient facilement par script ou par système de gestion de configuration : le script reçoit la chaîne de référence en paramètre unique et génère les fichiers dans les formats requis. Pour vérifier après déploiement, utilisez les commandes de la checklist récapitulative : elles ne nécessitent pas d'interactivité et conviennent aux tests automatiques.

Sécurité du stockage des mots de passe

Le minimum, c'est des droits 600 sur chaque fichier contenant un mot de passe. Mieux, c'est d'isoler les secrets dans des fichiers inclus séparés (include dans git, fichier séparé dans apt.conf.d uniquement pour les lignes d'authentification). Encore mieux, c'est un proxy sans authentification par mot de passe, mais avec restriction par IP, ou un agrégateur local comme évoqué plus haut. Et n'envoyez jamais les configs avec mots de passe entières dans les chats et les tickets.

FAQ : questions fréquentes sur la configuration

Faut-il maintenant supprimer les variables http_proxy de .bashrc ?

Pas obligatoirement. Les configs des outils ont priorité sur les variables, il n'y aura pas de conflit. Mais si vous voulez que seuls les gestionnaires de paquets passent par le proxy, et que le navigateur et les autres programmes aillent en direct, mieux vaut retirer les variables : elles influencent tout.

Pourquoi dans https-proxy de npm met-on une adresse en http:// et non en https:// ?

Parce que c'est l'adresse du serveur proxy lui-même, pas le protocole de la ressource cible. La plupart des proxys acceptent les connexions en HTTP simple et tunnelisent le HTTPS à l'intérieur. Si votre proxy accepte réellement les connexions TLS, alors mettez https://, mais c'est rare.

Peut-on utiliser un proxy SOCKS5 ?

npm : non, il ne prend en charge que les proxys HTTP. pip : oui, avec le paquet pysocks installé et une adresse du type socks5://host:port. git : oui, au format socks5h://host:port, la lettre h signifiant la résolution des noms côté proxy. apt : uniquement via des transports supplémentaires, pas en standard. Docker : non. En pratique, il est plus simple de demander au fournisseur un port HTTP.

Comment désactiver rapidement le proxy dans tous les outils ?

npm : npm config delete proxy et npm config delete https-proxy. pip : pip config unset global.proxy. git : git config --global --unset http.proxy. apt : supprimez ou renommez /etc/apt/apt.conf.d/80proxy. Docker : retirez le bloc proxies de daemon.json et config.json, puis redémarrez le service. Ou restaurez simplement les fichiers .bak des sauvegardes.

Où stocker les configs sous Windows ?

npm : C:\Users\NOM\.npmrc. pip : C:\Users\NOM\AppData\Roaming\pip\pip.ini. git : C:\Users\NOM\.gitconfig. Docker : C:\Users\NOM\.docker\config.json pour le client, et les réglages de Docker Desktop pour le démon. apt ne s'utilise pas sous Windows, sauf dans WSL, où les chemins Linux s'appliquent à l'intérieur du sous-système.

Cela fonctionne-t-il dans WSL ?

Oui, WSL est un Linux ordinaire, toutes les configs se trouvent aux chemins Linux à l'intérieur de la distribution. Notez que Docker Desktop avec l'intégration WSL utilise le démon côté Windows, donc les réglages du démon se font dans Docker Desktop, et le config.json client à l'intérieur de WSL dans le répertoire personnel.

Comment savoir quel outil a lu quel fichier ?

npm config list --json, pip config debug, apt-config dump, docker info, git config --show-origin --list. Chaque commande affiche non seulement les valeurs, mais aussi leur source. C'est la première chose à lancer en cas de débogage.

Pourquoi Docker Compose ne voit-il pas le proxy ?

Compose est un client, il utilise le même démon et le même ~/.docker/config.json. Si docker pull fonctionne mais pas docker compose pull, vérifiez que vous lancez compose sous le même utilisateur et que le fichier compose ne redéfinit pas les variables d'environnement des conteneurs, ce qui écraserait le proxy.

Peut-on définir des proxys différents pour npm et pip ?

Oui, c'est justement l'avantage des configs propres à chaque outil. Chaque fichier est indépendant. Par exemple, npm peut passer par un proxy et pip par un autre, avec une autre IP et une autre géolocalisation, si la tâche l'exige.

Conclusion

Récapitulons. Vous avez vérifié le proxy via curl et obtenu une chaîne de connexion de référence avec un mot de passe correctement encodé. Ensuite, vous l'avez déclarée à cinq endroits : dans ~/.npmrc pour npm, dans pip.conf pour pip, dans /etc/apt/apt.conf.d/80proxy pour apt, dans daemon.json et ~/.docker/config.json pour Docker, et dans ~/.gitconfig pour git. Pour chaque outil, vous avez défini des exclusions pour les hôtes internes là où c'est pris en charge, et vérifié que tout fonctionne même avec un environnement totalement purgé. C'est précisément ce qui distingue les configs propres aux outils des variables d'environnement : elles ne dépendent ni de qui, ni d'où, ni de quel service lance la commande.

Et maintenant ? Conservez les cinq fichiers de référence dans un dossier personnel et écrivez un petit script qui les déploie sur une nouvelle machine. Vérifiez les droits sur les fichiers contenant les mots de passe. Si des collègues ont le même problème, partagez-leur la checklist récapitulative : elle économise des heures de débogage.

Vers quoi évoluer ? Le niveau suivant, ce sont les proxys cacheurs et les registres privés pour les paquets, un proxy local agrégateur comme point d'entrée unique, et la vérification automatisée des réglages réseau dans les pipelines. Et si vous avez besoin de configurer un proxy non pas pour les outils, mais pour une session terminal précise ou une tâche en CI, il existe un guide séparé sur les variables d'environnement. Désormais, vous savez précisément où ses possibilités s'arrêtent et où celles des configs commencent.