Cómo configurar un proxy para npm, pip, apt, Docker y git: guía paso a paso con los archivos de configuración de cada herramienta
Contenido del artículo
- Introducción: por qué los gestores de paquetes necesitan su propia configuración de proxy
- Preparación previa
- Conceptos básicos: por qué no bastan las variables de entorno
- Paso 1: verificamos el proxy y preparamos la cadena de referencia
- Paso 2: configuramos npm a través del archivo .npmrc
- Paso 3: configuramos pip a través de pip.conf
- Paso 4: configuramos apt a través del directorio apt.conf.d
- Paso 5: configuramos docker en dos niveles
- Paso 6: configuramos git a través de git config
- Verificación del resultado: checklist final
- Errores típicos y soluciones
- Funcionalidades adicionales
- Faq: preguntas frecuentes sobre la configuración
- Conclusión
Introducción: por qué los gestores de paquetes necesitan su propia configuración de proxy
Seguramente ya te ha pasado: en la terminal tienes exportadas las variables http_proxy y https_proxy, curl descarga páginas sin problema, pero npm install se queda colgado un minuto y falla con error ETIMEDOUT. O apt update intenta en silencio llegar al mirror directamente, como si el proxy no existiera. O Docker al construir una imagen no puede bajar la capa base, aunque desde la misma consola docker pull funcione. Esto no es un bug ni misterio. Simplemente cada herramienta tiene su propia forma de leer la configuración de red, y las variables de entorno la cubren solo parcialmente.
Esta guía está dedicada precisamente a los archivos de configuración propios de cinco herramientas sin las cuales ningún desarrollador puede trabajar: npm (archivo .npmrc), pip (pip.conf o pip.ini), apt (directorio apt.conf.d), Docker (daemon.json y config.json) y git (git config). A propósito no repetimos el material sobre variables de entorno en la terminal y en CI. Aquí la tarea es otra: mostrar cómo escribir el proxy para que se aplique siempre, sin importar quién ni desde dónde ejecute el comando.
Como resultado obtendrás cinco configuraciones funcionales que puedes copiar a cualquier máquina, entenderás dónde busca cada herramienta su configuración y tendrás un conjunto de comandos para verificar. Además sabrás cómo revertir todo rápidamente.
Para quién es esta guía
- Desarrolladores cuyo portátil o servidor de trabajo está detrás de un proxy corporativo o doméstico.
- Testers y especialistas en automatización que necesitan que las compilaciones pasen por una dirección de proxy dedicada.
- Administradores que configuran imágenes típicas de estaciones de trabajo.
- Todos los que usan un proxy alquilado (incluido el móvil) para desarrollo y quieren que una herramienta concreta pase por él, no todo el sistema.
Qué necesitas saber de antemano
Bastan habilidades básicas de terminal: abrir la consola, navegar a un directorio, editar un archivo de texto. Usaremos el editor nano en Linux y el Bloc de notas en Windows, pero sirve cualquiera. Entender qué es una dirección IP y un puerto también ayuda, aunque recordaremos lo básico en la sección de conceptos.
Cuánto tiempo tomará
Si configuras las cinco herramientas seguidas, calcula entre 60 y 90 minutos. Cada herramienta por separado toma 10-15 minutos junto con la verificación. La etapa más larga es Docker, porque allí hay dos niveles de configuración y se requiere reiniciar el servicio.
Preparación previa
Antes de editar configuraciones, reunamos todo lo necesario. Saltarse esta etapa es la principal razón por la que después hay que pasar horas adivinando dónde está el error.
Datos necesarios sobre el proxy
Necesitas cuatro parámetros. Anótalos en un archivo de texto para no buscarlos en el chat:
- Tipo de proxy: HTTP o HTTPS (a veces SOCKS5, pero la mayoría de los gestores de paquetes esperan específicamente un proxy HTTP).
- Dirección: nombre de dominio o IP, por ejemplo proxy.corp.local o 10.20.30.40.
- Puerto: casi siempre 3128, 8080 u 8888.
- Usuario y contraseña, si el proxy requiere autenticación. Presta atención a los caracteres especiales en la contraseña: requerirán codificación, de eso hablamos abajo.
Requisitos del sistema y versiones
La instrucción está verificada con las versiones actuales de 2026 y sirve para:
- Ubuntu 22.04 y 24.04, Debian 12 y 13 (para apt).
- Node.js 20 y 22 con npm 10 y 11.
- Python 3.10 y superior con pip 24 y superior.
- Docker Engine 25 y superior (la clave proxies en daemon.json apareció en la versión 23, en versiones más antiguas usa el drop-in de systemd, mostraremos ambas opciones).
- Git 2.40 y superior.
Si usas Windows, todos los comandos para npm, pip y git funcionan en PowerShell sin cambios, solo cambian las rutas de los archivos. Para Docker Desktop la configuración del proxy se hace por la interfaz gráfica, también lo veremos.
Permisos de acceso
Para npm, pip y git bastan los permisos de un usuario normal: sus configuraciones están en el directorio personal. Para apt y Docker se necesitará sudo, porque los archivos están en /etc y cambian el comportamiento de los servicios del sistema.
Copias de seguridad
Antes de empezar, copia los archivos de configuración existentes. Un comando por archivo, y siempre podrás volver al estado original:
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/nullEl sufijo 2>/dev/null sirve para que el comando no se queje si el archivo aún no existe. Esto es normal: muchos usuarios no tienen .npmrc ni pip.conf al principio.
Consejo: crea en tu directorio personal una carpeta proxy-configs y guarda allí las versiones de referencia de las cinco configuraciones. Mudarte a una máquina nueva se convertirá en copiar cinco archivos.
Conceptos básicos: por qué no bastan las variables de entorno
Entendamos qué pasa bajo el capó, de lo contrario los pasos siguientes parecerán un conjunto de conjuros mágicos.
Qué es un proxy en el contexto de un gestor de paquetes
Un servidor proxy es un intermediario. En lugar de conectarse directamente con registry.npmjs.org, tu npm se conecta al proxy y le pide que vaya a registry.npmjs.org. Para recursos HTTPS se usa el método CONNECT: el proxy establece un túnel y el tráfico cifrado pasa por él sin descifrarse. Para el gestor de paquetes es importante conocer la dirección del proxy, el puerto y, si es necesario, las credenciales.
Cómo se enteran las herramientas del proxy
Existen tres capas de configuración, y se combinan en una cadena de prioridades:
- Flags de línea de comandos: por ejemplo, pip install --proxy. Actúan en una sola ejecución.
- Configuración propia de la herramienta: .npmrc, pip.conf y otros. Actúan siempre para esa herramienta.
- Variables de entorno: http_proxy, https_proxy, no_proxy. Actúan para todos los programas en la sesión actual que las lean.
La palabra clave es que las lean. Y aquí empiezan los problemas.
Cuatro razones por las que las variables de entorno no bastan
Primera razón: cambio de usuario. Cuando escribes sudo apt update, el comando se ejecuta como root, y sudo por defecto limpia el entorno (opción env_reset). Tus http_proxy quedan con el usuario normal. Es más, el propio apt descarga archivos bajo el usuario de servicio _apt, que no tiene tu sesión en absoluto.
Segunda razón: demonios y servicios. Docker Engine es un servicio en segundo plano, iniciado por systemd al arrancar el sistema. Nunca vio tu terminal. El comando docker pull solo envía una solicitud al demonio, y quien descarga la imagen es el demonio. Por eso las variables en tu consola no afectan a docker pull en absoluto.
Tercera razón: interpretación distinta. Unos programas leen solo http_proxy en minúsculas, otros solo HTTP_PROXY, otros ambas variantes. Versiones antiguas de npm ignoraban no_proxy. Algunas herramientas no entienden credenciales dentro de la variable. La configuración propia elimina las conjeturas.
Cuarta razón: granularidad. Una variable de entorno o existe o no existe. Y puede que necesites enviar a través del proxy solo github.com, pero no el GitLab interno. O ir a PyPI público a través del proxy, y al índice interno directamente. Esas reglas solo las saben las configuraciones: git admite configurar el proxy para una URL concreta, apt para un host concreto, Docker para una lista de exclusiones a nivel del demonio.
Codificación de caracteres especiales en la contraseña
El usuario y la contraseña en las configuraciones se pasan dentro de una URL del tipo http://usuario:contraseña@host:puerto. Los caracteres @, :, /, #, ?, % y el espacio dentro de la contraseña rompen el análisis de la dirección. Hay que reemplazarlos por códigos porcentuales: @ pasa a ser %40, : pasa a %3A, # pasa a %23, / pasa a %2F, % pasa a %25, el espacio pasa a %20. Por ejemplo, la contraseña p@ss:1 en la configuración se escribirá como p%40ss%3A1. Recuerda esta regla, te salvará en las cinco herramientas.
Paso 1: Verificamos el proxy y preparamos la cadena de referencia
Objetivo de la etapa: asegurarte de que el proxy funciona en general y obtener una cadena de conexión verificada que insertaremos en todas las configuraciones.
- Abre la terminal. En Linux es Ctrl+Alt+T, en Windows es PowerShell desde el menú Inicio.
- Arma la cadena de conexión con la plantilla http://USUARIO:CONTRASEÑA@DIRECCIÓN:PUERTO. Sin autenticación, simplemente http://DIRECCIÓN:PUERTO. Ejemplo: http://dev:s3cret@10.20.30.40:3128.
- Ejecuta una solicitud de prueba con curl, indicando explícitamente el proxy con el flag -x para no depender de las variables:
curl -x http://dev:s3cret@10.20.30.40:3128 -I https://registry.npmjs.org/ - Espera la respuesta. Debe comenzar con la línea HTTP/2 200 o HTTP/1.1 200 OK. Si ves 407 Proxy Authentication Required, el usuario o la contraseña están mal. Si ves Could not resolve proxy, hay una errata en la dirección. Si ves connection refused, el puerto está mal o el proxy está apagado.
- Repite la verificación para los demás destinos: https://pypi.org/simple/, https://deb.debian.org/, https://registry-1.docker.io/v2/, https://github.com/. Para Docker la respuesta 401 es normal, significa que llegaste al registro y él pide un token.
- Anota la cadena final en tu archivo de texto. Esta es tu cadena de referencia del proxy.
Atención: si la contraseña contiene caracteres especiales, codifícalos precisamente en este paso y verifica la variante codificada con curl. Así en todas las configuraciones siguientes insertarás una cadena ya comprobada.
Consejo: si tu proveedor te da no un proxy sino un pool de direcciones o un proxy móvil con rotación de IP, normalmente tiene un punto de entrada único: un host y un puerto detrás de los cuales las IP cambian automáticamente. Escribe en las configuraciones justamente ese punto de entrada, no IP concretas del pool, de lo contrario la configuración quedará obsoleta a la primera rotación.
Verificación: curl con el flag -x devuelve código 200 (o 401 para Docker Hub) en las cinco direcciones. Si al menos una no responde, no sigas: las configuraciones no arreglarán un proxy que no funciona.
Paso 2: Configuramos npm a través del archivo .npmrc
Objetivo de la etapa: que npm install, npm view y npm publish funcionen a través del proxy desde cualquier proyecto y cualquier consola, incluidas las entornos de desarrollo que lanzan npm por sí mismos.
Dónde vive la configuración de npm
npm lee la configuración de varios archivos en orden creciente de prioridad: valores integrados, archivo global en el directorio de instalación de npm, el de usuario ~/.npmrc (en Windows, C:\Users\NOMBRE\.npmrc) y el del proyecto .npmrc en la raíz del proyecto junto a package.json. Para el proxy casi siempre se usa el archivo de usuario: se aplica a todos los proyectos, pero no entra al repositorio.
Configuración paso a paso
- Define el proxy para el tráfico HTTP normal:
npm config set proxy http://dev:s3cret@10.20.30.40:3128 - Define el proxy para el tráfico HTTPS (el registro npm funciona por HTTPS, por eso esta configuración es la principal):
Ojo: el valor comienza con http://, no con https://. Es la dirección del propio proxy, y él normalmente acepta conexiones por HTTP simple, incluso cuando tunela HTTPS.npm config set https-proxy http://dev:s3cret@10.20.30.40:3128 - Si tienes un registro interno o mirror al que hay que ir directamente, agrega exclusiones separadas por comas:
El punto delante del dominio significa todos los subdominios.npm config set noproxy localhost,127.0.0.1,.corp.local - Abre el archivo y comprueba que las líneas se escribieron:
En Windows: type $env:USERPROFILE\.npmrc. Debes ver tres líneas con formato clave=valor.cat ~/.npmrc - Si el proxy corporativo sustituye certificados, agrega el certificado raíz de la empresa:
No desactives la verificación de certificados con strict-ssl=false sin extrema necesidad: eso abre camino a la sustitución de paquetes.npm config set cafile /etc/ssl/certs/corp-root.pem
La vía alternativa es crear el archivo a mano. El contenido de ~/.npmrc será así:
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.localCada par debe estar en su propia línea. Sin comillas ni espacios alrededor del signo igual.
Qué pasa con yarn y pnpm
Yarn Classic (1.x) lee el mismo ~/.npmrc y además su propio ~/.yarnrc con las claves proxy y https-proxy. Yarn Berry (2+) guarda la configuración en .yarnrc.yml: claves httpProxy y httpsProxy. pnpm es totalmente compatible con .npmrc, no hay que hacer nada adicional. También conviene recordar que npm ci y los IDE corporativos lanzan npm con el mismo usuario, así que el .npmrc de usuario los cubre también.
Consejo: el comando npm config list --json mostrará la configuración final teniendo en cuenta todos los archivos. Si ves proxy=null, significa que el archivo no se leyó: comprueba que esté en el directorio personal precisamente del usuario con el que ejecutas npm.
Verificación: ejecuta npm view lodash version. En 1-3 segundos debe volver una línea con el número de versión. Para mayor claridad puedes quitar temporalmente las variables de entorno (unset http_proxy https_proxy) y repetir: npm debe funcionar igual, porque lee .npmrc.
Posibles problemas
- ETIMEDOUT o ECONNRESET: dirección o puerto del proxy incorrectos, o el proxy bloquea CONNECT al puerto 443. Verifica la cadena de referencia con curl.
- 407 Proxy Authentication Required: error en el usuario o la contraseña, casi siempre un carácter especial sin codificar.
- UNABLE_TO_GET_ISSUER_CERT_LOCALLY: el proxy sustituye el certificado, hace falta cafile con el certificado raíz corporativo.
Paso 3: Configuramos pip a través de pip.conf
Objetivo de la etapa: que pip install y pip download funcionen a través del proxy, incluso dentro de entornos virtuales y al ejecutarse desde scripts de Python.
Dónde buscar pip.conf
pip usa tres niveles de archivos: global (para todo el sistema), de usuario y de entorno virtual. Las rutas dependen del sistema:
- Linux, de usuario: ~/.config/pip/pip.conf (la variante antigua ~/.pip/pip.conf también se lee).
- Linux, global: /etc/pip.conf.
- macOS, de usuario: ~/Library/Application Support/pip/pip.conf, y si esa carpeta no existe, ~/.config/pip/pip.conf.
- Windows, de usuario: %APPDATA%\pip\pip.ini, es decir C:\Users\NOMBRE\AppData\Roaming\pip\pip.ini.
- Dentro de un entorno virtual: el archivo pip.conf (o pip.ini) directamente en la raíz del directorio venv.
Para no adivinar, pregúntale al propio pip: el comando pip config debug mostrará todas las rutas que revisa y marcará los archivos existentes.
Configuración paso a paso
- Asegúrate de que pip está actualizado: pip --version. Debe ser versión 24 o superior.
- Define el proxy con un solo comando, pip mismo creará el archivo en el lugar correcto:
Aquí global significa la sección [global] del archivo, no el nivel del sistema. El archivo se crea de usuario.pip config set global.proxy http://dev:s3cret@10.20.30.40:3128 - Si el proxy sustituye certificados, indica el certificado raíz:
pip config set global.cert /etc/ssl/certs/corp-root.pem - Mira qué quedó:
Salida esperada: global.proxy='http://dev:s3cret@10.20.30.40:3128'.pip config list - Abre el archivo y verifica el formato. Debe verse así:
Cada línea aparte, la sección entre corchetes arriba.[global] proxy = http://dev:s3cret@10.20.30.40:3128 cert = /etc/ssl/certs/corp-root.pem
Una diferencia importante entre pip y npm: pip no tiene una configuración separada para el proxy HTTPS. Una sola clave proxy se usa para todas las conexiones. Y pip no tiene un equivalente directo de noproxy en la configuración: las exclusiones las toma solo de la variable de entorno no_proxy. Si necesitas ir a un índice interno directamente, es más fácil indicarle un index-url propio y ejecutar pip con el flag --proxy vacío para ese caso, o usar un pip.conf del proyecto dentro del venv sin la línea proxy.
Consejo: si tienes varios proyectos y en uno necesitas proxy y en otro no, coloca pip.conf en la raíz del entorno virtual correspondiente. La configuración del venv tiene prioridad sobre la de usuario, y obtendrás comportamientos distintos sin cambiar archivos globales.
Atención: no agregues trusted-host = pypi.org para silenciar los errores de certificado. Eso desactiva la verificación de autenticidad y permite que cualquier intermediario te coloque un paquete falso. La solución correcta es la clave cert con el certificado corporativo.
Verificación: ejecuta pip download requests --no-deps -d /tmp/piptest. En unos segundos aparecerá en el directorio el archivo requests-*.whl. Luego borra el directorio de prueba. Si quieres asegurarte de que funciona justo la configuración, quita las variables de entorno y repite.
Posibles problemas
- ProxyError o Cannot connect to proxy: errata en la dirección o puerto incorrecto. Compara con la cadena de referencia.
- Tunnel connection failed: 407: error de autorización. Comprueba la codificación de la contraseña.
- SSLError CERTIFICATE_VERIFY_FAILED: hace falta la clave cert con el certificado raíz del proxy.
- El archivo se escribió, pero pip no lo ve: estás ejecutando el pip de otro intérprete (por ejemplo, python3 -m pip de otro Python). Ejecuta pip config debug precisamente con el comando con el que instalas paquetes.
Paso 4: Configuramos apt a través del directorio apt.conf.d
Objetivo de la etapa: que sudo apt update y sudo apt install descarguen paquetes a través del proxy, y que las peticiones al mirror interno vayan directamente.
Por qué precisamente apt.conf.d
apt lee la configuración de /etc/apt/apt.conf y de todos los archivos del directorio /etc/apt/apt.conf.d/ en orden alfabético. La buena práctica es no tocar archivos ajenos, sino crear el tuyo con prefijo numérico. El número determina el orden de lectura: el archivo 80proxy se aplicará después de 01autoremove y otros del sistema. Justo aquí la configuración sobrevivirá a cualquier actualización del paquete apt.
Configuración paso a paso
- Crea un nuevo archivo de configuración:
Se abrirá un editor vacío.sudo nano /etc/apt/apt.conf.d/80proxy - Escribe dos líneas para los repositorios HTTP y HTTPS. Fíjate en las comillas y los puntos y coma: en la sintaxis de apt son obligatorios:
Acquire::http::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::https::Proxy "http://dev:s3cret@10.20.30.40:3128"; - Si hay un mirror interno para el que no se necesita proxy, agrega una línea con la exclusión. La palabra DIRECT en mayúsculas significa conexión directa:
Acquire::http::Proxy::mirror.corp.local "DIRECT"; - Guarda el archivo: en nano pulsa Ctrl+O, luego Enter, luego Ctrl+X para salir.
- Limita los permisos del archivo, pues contiene la contraseña:
Solo root podrá leer el contenido.sudo chmod 600 /etc/apt/apt.conf.d/80proxy - Comprueba que apt analizó el archivo sin errores de sintaxis:
Debes ver las líneas Acquire::http::Proxy y Acquire::https::Proxy con tus valores.apt-config dump | grep -i proxy
Aquí tienes un ejemplo completo del archivo para mayor claridad:
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";Alternativa para una sola ejecución sin archivo: sudo apt -o Acquire::http::Proxy="http://10.20.30.40:3128" update. El flag -o es cómodo para probar el valor antes de escribirlo en la configuración.
Consejo: los servidores proxy que cachean paquetes deb suelen tener un puerto aparte para apt. Pregúntale al administrador: si existe, apt update se acelerará varias veces gracias a la caché local.
Verificación: ejecuta sudo apt update. En la salida aparecerán líneas Hit o Get con direcciones de repositorios y no habrá líneas con Err. Fíjate en que no definimos variables de entorno y sudo las habría limpiado de todos modos, pero apt de todas formas salió a la red. Ese es el efecto de la configuración propia.
Posibles problemas
- Err: 407 Proxy Authentication Required: la autorización no pasó, verifica la codificación de caracteres especiales.
- Could not connect o Connection timed out: apt fue directamente. Lo más probable es una errata en el archivo, y apt-config dump no la muestra. Comprueba el uso de mayúsculas en Acquire y los dobles dos puntos.
- E: Syntax error: falta un punto y coma o una comilla al final de la línea.
- El archivo está en su lugar, pero la exclusión DIRECT no funciona: asegúrate de que el nombre del host en la línea de exclusión coincide con el de sources.list letra por letra, sin http:// y sin puerto.
Paso 5: Configuramos Docker en dos niveles
Objetivo de la etapa: que docker pull, docker build y docker compose pull descarguen imágenes a través del proxy, y que los contenedores, si es necesario, reciban automáticamente la configuración del proxy.
Dos niveles que a menudo se confunden
Docker tiene dos lugares independientes donde se necesita el proxy de forma distinta:
- Nivel del demonio (servicio dockerd). Es él quien descarga las imágenes del registro. Se configura en /etc/docker/daemon.json o a través de systemd. Requiere reiniciar el servicio.
- Nivel del cliente (archivo ~/.docker/config.json). No influye en la descarga de imágenes. En cambio, transmite automáticamente las variables del proxy dentro de los contenedores que se ejecutan y en el proceso de compilación, para que apt o pip dentro del contenedor también vean el proxy.
Si configuras solo el cliente, docker pull no funcionará. Si configuras solo el demonio, las imágenes se descargan, pero RUN apt-get update dentro del Dockerfile fallará. Se necesitan ambos.
Parte A: el demonio a través de daemon.json
- Verifica la versión: docker version. Si la versión del servidor es 23.0 o superior, usa daemon.json. Si es más antigua, pasa a la parte B.
- Abre el archivo de configuración del demonio:
Si el archivo ya existe y contiene otras claves, agrega el bloque proxies dentro de las mismas llaves, separado por comas. Si no existe, créalo desde cero.sudo nano /etc/docker/daemon.json - Escribe el bloque de configuración:
Ojo: las claves se escriben con guion y en minúsculas exactamente así. Este es el formato del demonio, en el cliente las claves serán otras.{ "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" } } - Guarda el archivo (Ctrl+O, Enter, Ctrl+X).
- Comprueba que el JSON es válido, de lo contrario el demonio no arrancará:
Si el comando mostró el contenido del archivo con sangrías, la sintaxis es correcta. Si se queja con Expecting value o Extra data, busca una coma de más o de menos.python3 -m json.tool /etc/docker/daemon.json - Reinicia el servicio:
El reinicio tomará de 5 a 15 segundos. Todos los contenedores en ejecución se detendrán, así que hazlo en un momento tranquilo.sudo systemctl restart docker - Asegúrate de que el demonio se levantó: sudo systemctl status docker. Debe aparecer active (running) en verde.
Atención: una coma de más en daemon.json y Docker no arranca en absoluto, y con él caerán todos los contenedores de la máquina. Verifica siempre el archivo con json.tool antes de reiniciar y ten una copia de seguridad a mano.
Parte B: el demonio a través de systemd (para versiones antiguas y como alternativa)
- Crea el directorio para configuraciones adicionales del servicio: sudo mkdir -p /etc/systemd/system/docker.service.d
- Crea el archivo: sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf
- Escribe:
[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" - Guarda y aplica: sudo systemctl daemon-reload, luego sudo systemctl restart docker.
Sí, aquí se usan variables de entorno, pero no están definidas en tu consola, sino en la definición del servicio: el demonio las recibe al arrancar desde systemd. Es la única forma para Docker anterior a la versión 23. Si tienes definidos tanto daemon.json como el archivo systemd, la prioridad es de daemon.json.
Parte C: el cliente a través de ~/.docker/config.json
- Abre o crea el archivo nano ~/.docker/config.json. Si el archivo ya contiene el bloque auths con tus credenciales de registros, no lo borres, agrega un bloque nuevo al lado separado por comas.
- Escribe:
Aquí las claves son estilo camelCase: httpProxy, httpsProxy, noProxy. Esta es la diferencia con daemon.json, y no se deben confundir.{ "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" } } } - Guarda el archivo. No se requiere reinicio, el cliente lo lee en cada comando.
Ahora en docker run y docker build, dentro del contenedor entrarán automáticamente las variables HTTP_PROXY, HTTPS_PROXY y NO_PROXY (en ambos registros). Eso significa que apt-get y pip dentro del Dockerfile también irán a través del proxy sin ARG ni ENV manuales.
Docker Desktop en Windows y macOS
Abre la configuración desde el ícono en la bandeja, sección Resources, subsección Proxies. Activa Manual proxy configuration, escribe la dirección en los campos Web Server (HTTP) y Secure Web Server (HTTPS), la lista de exclusiones en Bypass proxy settings for these hosts and domains. Pulsa Apply and restart. El config.json del cliente en Windows está en C:\Users\NOMBRE\.docker\config.json y se configura igual que se describió arriba.
Consejo: el comando docker info muestra una sección con HTTP Proxy, HTTPS Proxy y No Proxy. Es la forma más rápida de saber si el demonio vio tu configuración, sin lanzar una descarga.
Verificación: ejecuta docker pull hello-world. La imagen pesa unos pocos kilobytes y se descargará en un par de segundos, al final aparecerá Status: Downloaded newer image. Luego verifica la parte del cliente: docker run --rm alpine env | grep -i proxy. En la salida deben estar las líneas HTTP_PROXY y HTTPS_PROXY con tu dirección.
Posibles problemas
- Docker no arranca tras editar daemon.json: error de sintaxis. Mira sudo journalctl -u docker -n 30, allí se indicará la línea con el error. Restaura desde la copia de seguridad.
- docker pull se queda colgado y falla por timeout, aunque docker info muestra el proxy: el demonio no se reinició tras la edición, o el proxy no deja pasar CONNECT a registry-1.docker.io. Verifica la cadena de referencia con curl.
- Dentro de la compilación apt-get update falla, pero docker pull funciona: no está configurado el config.json del cliente, o la compilación va por un builder remoto que lee otro archivo.
- El contenedor recibió el proxy, pero no puede llegar a un contenedor vecino: agrega los nombres de servicios internos y la subred de Docker en noProxy.
Paso 6: Configuramos git a través de git config
Objetivo de la etapa: que git clone, fetch, pull y push por HTTPS vayan a través del proxy, y que para el servidor interno se pueda dejar la conexión directa, y para un hosting concreto, definir un proxy aparte.
Dónde guarda git su configuración
Tres niveles: del sistema (/etc/gitconfig), global del usuario (~/.gitconfig, en Windows, C:\Users\NOMBRE\.gitconfig) y local dentro del repositorio (.git/config). El proxy normalmente se define globalmente, y las exclusiones puntuales también globalmente, pero con referencia a la URL.
Configuración paso a paso
- Define el proxy para todas las conexiones HTTPS y HTTP con un solo comando:
A diferencia de npm, git no tiene un https.proxy aparte para el protocolo HTTPS: la clave http.proxy se aplica a ambos. La configuración https.proxy aparece en instrucciones antiguas, pero no es una clave estándar de git y se ignora.git config --global http.proxy http://dev:s3cret@10.20.30.40:3128 - Si para el servidor interno no se necesita proxy, define un valor vacío precisamente para su URL:
La cadena vacía significa conexión directa. La parte entre http. y .proxy es el prefijo de URL al que se aplica la regla.git config --global http.https://git.corp.local.proxy "" - Si para un hosting concreto se necesita otro proxy (por ejemplo, uno móvil dedicado), indícalo igual con referencia a la URL:
git config --global http.https://github.com.proxy http://dev:s3cret@10.20.30.41:3128 - Si el proxy sustituye certificados, agrega el certificado raíz:
git config --global http.sslCAInfo /etc/ssl/certs/corp-root.pem - Verifica el archivo final:
Verás las líneas http.proxy=... y http.https://git.corp.local.proxy= con valor vacío.git config --global --list | grep -i proxy
El archivo ~/.gitconfig tras estos comandos se verá así:
[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:3128Tal granularidad es inalcanzable a través de variables de entorno: no_proxy solo sabe excluir hosts, pero no asignar proxies distintos a servidores distintos.
Qué pasa con las direcciones SSH
La configuración http.proxy no afecta a direcciones del tipo git@github.com:usuario/repo.git, porque es protocolo SSH, no HTTP. Si tu proxy permite tunelar al puerto 22 a través de CONNECT, se puede configurar el cliente SSH en el archivo ~/.ssh/config con la directiva ProxyCommand y la utilidad nc o corkscrew. Pero muchos proxies corporativos prohíben tales conexiones. El camino más simple y predecible es cambiar las direcciones remotas a HTTPS: git remote set-url origin https://github.com/usuario/repo.git y usar un token de acceso en lugar de la contraseña.
Consejo: para no guardar la contraseña del proxy en ~/.gitconfig en texto plano, puedes ponerla en un archivo aparte con permisos 600 y conectarla con la directiva include. Crea ~/.gitconfig-proxy con la sección [http], y en el archivo principal agrega [include] path = ~/.gitconfig-proxy. Así el config principal se podrá mostrar tranquilamente a los colegas.
Verificación: ejecuta git ls-remote https://github.com/git/git.git HEAD. En un par de segundos volverá una línea con el hash del commit y la palabra HEAD. El comando no crea archivos ni clona nada, es la prueba ideal de la parte de red. Luego comprueba la exclusión: git ls-remote al servidor interno debe funcionar incluso con el proxy caído.
Posibles problemas
- Failed to connect to proxy o Could not resolve proxy: errata en la dirección.
- Received HTTP code 407 from proxy after CONNECT: error de autorización, verifica la codificación de la contraseña.
- SSL certificate problem: unable to get local issuer certificate: hace falta http.sslCAInfo. No uses http.sslVerify false de forma permanente.
- La regla para URL no se aplica: el prefijo debe coincidir con el inicio de la dirección en el remote. Si el remote está escrito como https://www.github.com, la regla para https://github.com no funcionará.
Verificación del resultado: checklist final
Después de configurar las cinco herramientas, haz una comprobación final. Está construida a propósito para excluir la influencia de las variables de entorno y asegurarte de que funcionan precisamente las configuraciones.
- Abre una terminal nueva y quita las variables si están definidas: unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY. En PowerShell: Remove-Item Env:HTTP_PROXY y análogamente para las demás.
- Verifica npm: npm view express version. Se espera un número de versión.
- Verifica pip: pip download six --no-deps -d /tmp/t. Se espera un archivo whl descargado.
- Verifica apt: sudo apt update. Se esperan líneas Hit o Get sin Err.
- Verifica Docker: docker pull hello-world y docker run --rm alpine env | grep -i proxy. Se espera una imagen descargada y variables en el contenedor.
- Verifica git: git ls-remote https://github.com/git/git.git HEAD. Se espera el hash del commit.
Indicadores de éxito
- Los seis comandos funcionaron sin variables de entorno en la consola.
- En los archivos .npmrc, pip.conf, 80proxy, daemon.json, config.json y .gitconfig está escrita la misma cadena de referencia del proxy.
- Los archivos con contraseñas (80proxy, daemon.json, .npmrc, pip.conf, .gitconfig) tienen permisos 600 o son accesibles solo para root.
- Las exclusiones para hosts internos funcionan: el acceso a ellos pasa incluso con el proxy apagado.
- Las copias de seguridad de los archivos originales están a mano y sabes cómo restaurarlas.
Verificación: si al menos un punto no se cumple, vuelve a la sección de la herramienta correspondiente y compara tu archivo con el ejemplo de la guía símbolo por símbolo. En nueve de cada diez casos la causa es una errata o un carácter sin codificar en la contraseña.
Errores típicos y soluciones
Error 1: código 407 Proxy Authentication Required en todas partes
Causa: la contraseña contiene un carácter especial (@, :, #, %) que no fue codificado, y la herramienta analizó la dirección mal.
Solución: codifica los caracteres con códigos porcentuales (@ a %40, : a %3A, # a %23, % a %25) y verifica la nueva cadena con curl -x antes de escribirla en las configuraciones.
Error 2: funciona desde la terminal, no funciona con sudo
Causa: sudo limpia el entorno, y todavía no creaste la configuración. El clásico de apt.
Solución: crea /etc/apt/apt.conf.d/80proxy como en el Paso 4. Para las demás herramientas bajo root recuerda que root lee su propio directorio personal /root, no el tuyo: si necesitas npm o pip desde root, la configuración debe estar en /root/.npmrc o /root/.config/pip/pip.conf.
Error 3: Docker no arranca tras editar daemon.json
Causa: JSON inválido: coma sobrante tras el último elemento, llave faltante, comillas simples en lugar de dobles.
Solución: ejecuta sudo journalctl -u docker -n 30, encuentra la línea con el error, corrige el archivo y verifícalo con python3 -m json.tool antes del siguiente reinicio. En el peor caso, restaura daemon.json.bak.
Error 4: docker pull funciona, pero apt-get dentro del Dockerfile falla
Causa: está configurado el demonio, pero no el cliente. Los procesos dentro del contenedor no heredan la configuración del demonio.
Solución: crea ~/.docker/config.json con el bloque proxies.default como en la parte C del Paso 5. Después de eso docker build transmitirá automáticamente las variables a las etapas RUN.
Error 5: errores de certificado SSL en todas las herramientas
Causa: el proxy realiza inspección de tráfico y coloca su propio certificado, en el que el sistema no confía.
Solución: obtén del administrador el certificado raíz del proxy en formato PEM y especifícalo: npm cafile, pip cert, git http.sslCAInfo. Para apt y Docker basta agregar el certificado al almacén del sistema: cópialo en /usr/local/share/ca-certificates/ y ejecuta sudo update-ca-certificates, luego reinicia Docker. No desactives la verificación de certificados con los flags strict-ssl, trusted-host y sslVerify.
Error 6: pip ignora pip.conf
Causa: en la máquina hay varias versiones de Python, y editas la configuración de una pero ejecutas otra. O el archivo está en una ubicación antigua que la versión concreta no lee.
Solución: ejecuta python3 -m pip config debug con el mismo comando con el que instalas paquetes. La salida mostrará qué archivos se encontraron. Pasa la configuración a la ruta de usuario encontrada.
Error 7: git pasa por el proxy incluso hacia el servidor interno
Causa: la regla de exclusión está definida para una URL que no coincide con la dirección del remote. O está definida en el .git/config local de otro repositorio.
Solución: mira la dirección exacta con git remote -v, copia su inicio hasta el nombre del host y define la regla http.URL_EXACTA.proxy con valor vacío a través de --global.
Error 8: todo funcionaba y tras cambiar la contraseña del proxy se rompió
Causa: la contraseña está incrustada en cinco archivos distintos, no actualizaste todos.
Solución: usa el comando grep -rl 'contraseña_vieja' ~/.npmrc ~/.config/pip ~/.gitconfig ~/.docker y sudo grep -rl para /etc/apt/apt.conf.d y /etc/docker, para encontrar todas las ocurrencias, y actualiza cada una. Luego pasa el checklist final.
Funcionalidades adicionales
Proxy agregador local como punto de entrada único
Si las credenciales del proxy cambian con frecuencia o el pool de direcciones rota, es cómodo levantar en tu máquina un proxy local ligero (por ejemplo, en 127.0.0.1:3128) que sepa a dónde ir y con qué datos. Entonces en las cinco configuraciones se escribe una sola dirección sin contraseña, y el cambio de credenciales se hace en un solo lugar. Esto también resuelve el problema de las herramientas que funcionan mal con autenticación en la URL.
Mirrors y proxies caché para paquetes
El proxy no tiene que ser universal. Para apt existen proxies caché que guardan los archivos deb localmente y los sirven a toda la oficina. Para npm y pip las corporaciones instalan registros privados que hacen de proxy de los públicos y además cachean. En tal caso, en lugar de la clave proxy se usa registry en .npmrc e index-url en pip.conf, y el proxy hacia el mundo exterior se configura ya en ese registro. Para Docker un papel análogo lo cumple la clave registry-mirrors en daemon.json.
Configuraciones separadas para distintos proyectos
El .npmrc del proyecto junto a package.json, el pip.conf dentro del venv y el .git/config local permiten que un proyecto vaya a través del proxy y otro directamente. Solo no hagas commit de archivos con contraseñas en el repositorio: agrégalos a .gitignore o usa variables de sustitución del tipo ${PROXY_URL}, que npm sabe expandir desde el entorno al leer .npmrc.
Automatización del despliegue
Las cinco configuraciones son archivos de texto simples. Es cómodo desplegarlas con un script o un sistema de gestión de configuración: el script recibe la cadena de referencia como un solo parámetro y genera los archivos en los formatos necesarios. Para verificar tras el despliegue usa los comandos del checklist final: no requieren interactividad y sirven para pruebas automáticas.
Seguridad del almacenamiento de contraseñas
Lo mínimo son permisos 600 en cada archivo con contraseña. Mejor es sacar los secretos a archivos conectados aparte (include en git, archivo separado en apt.conf.d solo para las líneas con autorización). Aún mejor es un proxy sin autenticación por contraseña, pero con restricción por IP, o un agregador local como el mencionado arriba. Y nunca envíes configuraciones con contraseñas a chats y tickets completas.
FAQ: preguntas frecuentes sobre la configuración
¿Hay que borrar ahora las variables http_proxy de .bashrc?
No es obligatorio. Las configuraciones de las herramientas tienen prioridad sobre las variables, no habrá conflicto. Pero si quieres que solo los gestores de paquetes vayan a través del proxy y el navegador y otros programas vayan directamente, es mejor quitar las variables: afectan a todo.
¿Por qué en https-proxy para npm se escribe una dirección con http:// y no con https://?
Porque es la dirección del propio servidor proxy, no el protocolo del recurso destino. La mayoría de los proxies aceptan conexiones por HTTP normal y tunelan HTTPS dentro. Si tu proxy realmente acepta conexiones TLS, entonces escribe https://, pero eso es poco común.
¿Se puede usar un proxy SOCKS5?
npm no, solo admite proxy HTTP. pip sí, con el paquete pysocks instalado y una dirección del tipo socks5://host:puerto. git sí, formato socks5h://host:puerto, la letra h significa resolución de nombres del lado del proxy. apt solo a través de transportes adicionales, de forma estándar no. Docker no. En la práctica es más fácil obtener un puerto HTTP del proveedor.
Cómo desactivar rápidamente el proxy en todas las herramientas
npm: npm config delete proxy y npm config delete https-proxy. pip: pip config unset global.proxy. git: git config --global --unset http.proxy. apt: borra o renombra /etc/apt/apt.conf.d/80proxy. Docker: borra el bloque proxies de daemon.json y config.json, reinicia el servicio. O simplemente restaura los archivos .bak de las copias de seguridad.
Dónde guardar las configuraciones en Windows
npm: C:\Users\NOMBRE\.npmrc. pip: C:\Users\NOMBRE\AppData\Roaming\pip\pip.ini. git: C:\Users\NOMBRE\.gitconfig. Docker: C:\Users\NOMBRE\.docker\config.json para el cliente y la configuración de Docker Desktop para el demonio. apt en Windows no se usa, salvo en WSL, donde se aplican las rutas de Linux dentro de la subsistema.
¿Funciona esto dentro de WSL?
Sí, WSL es un Linux normal, todas las configuraciones están en rutas de Linux dentro de la distribución. Ten en cuenta que Docker Desktop con integración WSL usa el demonio del lado de Windows, por eso la configuración del demonio se hace en Docker Desktop, y el config.json del cliente, dentro de WSL en el directorio personal.
Cómo entender qué archivo leyó cada herramienta
npm config list --json, pip config debug, apt-config dump, docker info, git config --show-origin --list. Cada comando muestra no solo los valores, sino también el origen de donde se tomaron. Esto es lo primero que conviene ejecutar al depurar.
Por qué Docker Compose no ve el proxy
Compose es un cliente, usa el mismo demonio y el mismo ~/.docker/config.json. Si docker pull funciona y docker compose pull no, comprueba que ejecutas compose con el mismo usuario y que en el archivo compose no estén sobrescritas las variables de entorno de los contenedores que pisan el proxy.
¿Se pueden definir proxies distintos para npm y pip?
Sí, en eso está la ventaja de las configuraciones propias. Cada archivo es independiente. Por ejemplo, npm puede ir por un proxy y pip por otro, con otra IP y otra geolocalización, si la tarea lo requiere.
Conclusión
Resumamos. Verificaste el proxy con curl y obtuviste una cadena de conexión de referencia con la contraseña correctamente codificada. Luego la escribiste en cinco lugares: en ~/.npmrc para npm, en pip.conf para pip, en /etc/apt/apt.conf.d/80proxy para apt, en daemon.json y ~/.docker/config.json para Docker, y en ~/.gitconfig para git. Para cada herramienta definiste exclusiones para hosts internos donde se admite, y te aseguraste de que todo funciona incluso con el entorno totalmente limpio. Esto es precisamente lo que distingue a las configuraciones propias de las variables de entorno: no dependen de quién, desde dónde y a través de qué servicio ejecutó el comando.
Qué hacer después. Guarda las cinco configuraciones de referencia en una carpeta personal y escribe un script corto que las despliegue en una máquina nueva. Verifica los permisos de los archivos con contraseñas. Si tienes colegas con el mismo problema, comparte con ellos el checklist final: ahorra horas de depuración.
Hacia dónde crecer. El siguiente nivel son los proxies caché y los registros privados de paquetes, el proxy agregador local como punto de entrada único y la verificación automatizada de la configuración de red en los pipelines. Y si necesitas configurar el proxy no para herramientas, sino para una sesión concreta de terminal o una tarea en CI, para eso hay una guía aparte sobre variables de entorno. Ahora sabes con certeza dónde terminan sus posibilidades y empiezan las de las configuraciones.