---
title: "Proxy en npm: cómo configurar npm detrás de un proxy"
description: "Configura el proxy de npm con npm config set proxy y https-proxy, o con HTTPS_PROXY. Orden de .npmrc, contraseñas con caracteres especiales, noproxy y errores."
url: https://proxynet.io/es/blog/npm-proxy-settings
date: 2026-11-19
author: "Acar Diveroli"
category: "Tutoriales"
lang: es
---

# Proxy en npm: cómo configurar npm detrás de un proxy

Abres un proyecto en un portátil nuevo del trabajo, ejecutas `npm install` y durante veinte segundos no pasa nada. Luego aparece `npm error code ETIMEDOUT`, seguido de una pista de que quizá estás detrás de un proxy. El registro se abre sin problemas en el navegador de la misma máquina, porque el navegador usa el proxy de la empresa que le pasan Windows o macOS. npm no lee esos ajustes del sistema. Necesita los suyos.

Esta guía cubre las tres formas de darle un proxy a npm (`npm config`, archivos `.npmrc` y variables de entorno), el orden en que npm las lee, las contraseñas con caracteres especiales, cómo comprobar y quitar los ajustes, cómo dejar los hosts internos fuera del proxy y los errores habituales. Ejecutamos cada comando en Windows 11 con Node.js 24.22.2 y npm 11.19.1, contra un proxy local que anotaba cada petición y pedía contraseña, siempre con un archivo de configuración desechable.

> **Nota: Respuesta breve**
>
> Ejecuta `npm config set proxy http://user:pass@pr.proxynet.io:8000` y `npm config set https-proxy http://user:pass@pr.proxynet.io:8000`. Las dos líneas van a tu `.npmrc` de usuario y se aplican a cada `npm install` posterior. Codifica los caracteres especiales de la contraseña (`@` como `%40`, `:` como `%3A`, `#` como `%23`), pon los hosts internos en `noproxy` y comprueba el resultado con `npm config list`, que oculta la contraseña. En lugar del archivo de configuración puedes definir `HTTPS_PROXY`; npm la lee para el registro, mientras que `HTTP_PROXY` sola no desvió nuestro tráfico al registro. Quita los ajustes con `npm config delete proxy` y `npm config delete https-proxy`.

## ¿Cuándo necesita npm un proxy?

npm necesita un proxy siempre que la máquina no puede llegar al registro directamente o debe llegar desde una dirección conocida. El registro (registry) es el servidor que aloja los paquetes; para la mayoría de los proyectos es `https://registry.npmjs.org`, pero una empresa puede tener el suyo propio.

Dos situaciones cubren casi todos los casos. Una red corporativa solo deja salir el tráfico a través de un proxy, así que una conexión directa al registro agota el tiempo de espera. O un registro privado acepta peticiones solo desde direcciones IP permitidas, y tu portátil o tu runner de CI no tiene una fija. En ambos casos hay que decirle a npm dónde está el proxy, porque no toma prestados los ajustes de proxy del sistema operativo como hace un navegador.

## ¿Cómo envía npm una petición a través de un proxy?

npm habla primero con el proxy y le pide que abra un túnel hacia el registro. Estos son los pasos que anotó nuestro proxy de pruebas durante `npm view semver version`:

1. **npm elige una dirección de proxy.** Usa `https-proxy` si está definido y, si no, `proxy`. Solo cuando ambos están vacíos mira la variable de entorno `HTTPS_PROXY`.
2. **npm revisa la lista de exclusión.** Si el host del registro coincide con una entrada de `noproxy` (o `NO_PROXY`), se salta el proxy y npm se conecta directamente.
3. **npm abre una conexión TCP con el proxy y envía `CONNECT registry.npmjs.org:443`.** Si la dirección del proxy contiene usuario y contraseña, npm los manda en una cabecera `Proxy-Authorization` ya con esta primera petición. Nuestro log no mostró ninguna ida y vuelta extra: `CONNECT registry.npmjs.org:443 auth user=user (ok)`.
4. **El proxy responde `200 Connection Established`** y a partir de ahí solo retransmite bytes. El handshake TLS se hace entre npm y el registro dentro del túnel, así que el proxy ve el nombre del host y el puerto, no los paquetes.
5. **npm descarga los metadatos y los tarballs** y los guarda en su caché local, algo que importa más adelante cuando depures.

## ¿Cómo se configura el proxy de npm?

Dos comandos `npm config set` lo configuran para tu cuenta de usuario:

```bash
npm config set proxy http://user:pass@pr.proxynet.io:8000
npm config set https-proxy http://user:pass@pr.proxynet.io:8000
```

npm los escribe en el archivo `.npmrc` de tu usuario (`~/.npmrc` en macOS y Linux, `C:\Users\<name>\.npmrc` en Windows). En nuestra máquina de prueba, el archivo contenía después exactamente estas líneas:

```ini
proxy=http://user:pass@pr.proxynet.io:8000
https-proxy=http://user:pass@pr.proxynet.io:8000
```

Fíjate en que `https-proxy` también empieza por `http://`. El esquema describe la conexión con el proxy, no con el registro: el proxy recibe HTTP simple de npm y lleva el tráfico HTTPS dentro del túnel `CONNECT`. Escribe `https://` solo si el propio proxy espera TLS en ese puerto.

Define las dos claves. En nuestra prueba, `proxy` sola bastó para el registro HTTPS, porque npm recurre a ella cuando `https-proxy` está vacía, pero no todas las herramientas que leen los ajustes de npm aplican la misma alternativa. npm rechaza las claves desconocidas, así que un error de tecleo como `npm config set proxi …` termina con ``npm error `proxi` is not a valid npm option``.

Si la máquina tiene una IP fija, la lista de IP autorizadas de Proxynet te permite dejar las credenciales fuera de la URL: entonces `http://pr.proxynet.io:8000` es todo el ajuste.

## ¿Qué ajustes lee npm y en qué orden?

npm combina ajustes de varias fuentes, y gana la más específica. La [documentación de configuración de npm](https://docs.npmjs.com/cli/v11/using-npm/config) fija la prioridad así: primero las opciones de la línea de comandos, después las variables de entorno que empiezan por `npm_config_`, luego los archivos `.npmrc` y por último los valores predeterminados integrados.

| Fuente | Ejemplo | Alcance |
|---|---|---|
| Opción de la línea de comandos | `--https-proxy http://…` | Un comando |
| Variable `npm_config_*` | `npm_config_https_proxy` | La shell actual |
| `.npmrc` del proyecto | `<project>/.npmrc` | Ese proyecto |
| `.npmrc` del usuario | `~/.npmrc` | Tu cuenta |
| `npmrc` global | `$PREFIX/etc/npmrc` | Todos los usuarios de ese Node.js |
| `npmrc` integrado | en la carpeta de instalación de npm | Esa copia de npm |

Comprobamos el orden con un archivo desechable: `npm_config_proxy=http://env.example:3128` se impuso al archivo de usuario, y `--proxy http://cli.example:3128` se impuso a ambos. Los nombres de las variables de entorno no distinguen mayúsculas de minúsculas, y los guiones pasan a ser guiones bajos, así que la clave `https-proxy` se convierte en `npm_config_https_proxy`.

La opción `--location` de `npm config set` elige el archivo: `user` es el valor predeterminado, `project` escribe el `.npmrc` junto a tu `package.json` y `global` escribe el archivo bajo el prefijo de npm. Un `.npmrc` de proyecto es práctico cuando solo un repositorio necesita el proxy, pero suele subirse al control de versiones, así que no metas contraseñas en él. La [referencia de .npmrc](https://docs.npmjs.com/cli/v11/configuring-npm/npmrc) documenta además la sustitución `${VARIABLE_NAME}`: una línea como `https-proxy=${NPM_PROXY_URL}` lee la URL completa del proxy de una variable de entorno cuando npm arranca, y así el secreto no queda en el archivo. Lo probamos; con la variable sin definir, npm dejó en su sitio el texto literal `${NPM_PROXY_URL}`.

## ¿Funcionan HTTP_PROXY y HTTPS_PROXY con npm?

`HTTPS_PROXY` funciona; `HTTP_PROXY` por sí sola no desvió el tráfico del registro en nuestra prueba. Con `HTTPS_PROXY` definida y ningún proxy en ningún `.npmrc`, cada petición al registro pasó por nuestro proxy. Con solo `HTTP_PROXY`, `npm view` se conectó directamente y el log del proxy quedó vacío, aunque la propia descripción de `https-proxy` en npm menciona `HTTP_PROXY` como alternativa. El código de npm 11.19.1 solo lee `HTTPS_PROXY` para las direcciones `https://`, y el registro público funciona sobre HTTPS.

El patrón seguro para una shell, un contenedor o un trabajo de CI es definir las dos, más las exclusiones:

```bash
export HTTPS_PROXY="http://user:pass@pr.proxynet.io:8000"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1,.internal.example"
```

En Windows PowerShell, las mismas líneas son `$env:HTTPS_PROXY = "http://user:pass@pr.proxynet.io:8000"` y así sucesivamente. Una trampa: `npm config get https-proxy` imprime `null` aunque `HTTPS_PROXY` esté definida, porque npm aplica la variable solo en el momento de enviar una petición. No interpretes ese `null` como «sin proxy».

## ¿Cómo se ponen usuario y contraseña en la URL del proxy?

Escríbelos delante del host como `user:password@` y aplica codificación porcentual a cada carácter que tenga un significado en una URL. La codificación porcentual sustituye un carácter por `%` y su código hexadecimal. Los caracteres que rompen una URL de proxy son los delimitadores que enumera la [RFC 3986, sección 2.2](https://www.rfc-editor.org/rfc/rfc3986.html#section-2.2): `:`, `/`, `?`, `#`, `[`, `]` y `@`. Un espacio y el propio `%` también hay que codificarlos.

| Carácter | Codificado |
|---|---|
| `@` | `%40` |
| `:` | `%3A` |
| `#` | `%23` |
| `/` | `%2F` |
| `%` | `%25` |
| espacio | `%20` |

Nuestro proxy de prueba aceptaba la contraseña `p@ss:w#rd`. Escrita tal cual, como `http://user:p@ss:w#rd@127.0.0.1:18080`, npm ni siquiera llegó al proxy: Node.js avisó de que la URL no era válida y npm se detuvo con `getaddrinfo ENOTFOUND ss`. Había tomado el texto tras la primera `@` como nombre del host. Codificada como `http://user:p%40ss%3Aw%23rd@127.0.0.1:18080`, el mismo comando devolvió la versión del paquete y el proxy anotó un inicio de sesión correcto. Si un error de DNS nombra un host que nunca escribiste, mira primero la contraseña.

## ¿Cómo se comprueban y se quitan los ajustes de proxy de npm?

`npm config list` muestra cada ajuste que difiere del predeterminado y el archivo del que procede. En nuestra ejecución, la salida empezaba con una línea que nombraba la fuente, `; "user" config from …\test.npmrc`, seguida de `proxy = "http://user:***@pr.proxynet.io:8000"`. npm enmascara la contraseña en esta vista, así que puedes pegar la salida en una incidencia de soporte sin riesgo.

`npm config get proxy` se niega a imprimir un valor que contenga una contraseña: `The proxy option is protected, and cannot be retrieved in this way`. Sin credenciales en la URL, imprime la dirección tal como está guardada; `npm config edit` abre el propio archivo.

Para quitar el proxy, borra las dos claves:

```bash
npm config delete proxy
npm config delete https-proxy
```

Cada `delete` elimina una línea de un archivo; en nuestra prueba, la línea `https-proxy` siguió ahí hasta que la borramos por separado. Añade `--location=project` o `--location=global` para los otros archivos, y revisa `HTTPS_PROXY` y `npm_config_https_proxy` en tu shell, porque una variable olvidada sigue desviando el tráfico aunque el archivo esté limpio. Para saltarte el proxy en un solo comando sin tocar el archivo, pasa el host del registro como exclusión: `--noproxy registry.npmjs.org`.

## ¿Cómo se dejan algunos hosts fuera del proxy?

Ponlos en `noproxy`, separados por comas. npm compara el nombre del host segmento a segmento desde la derecha, así que `.internal.example` coincide con `registry.internal.example` y con cualquier otro nombre bajo ese dominio.

```bash
npm config set noproxy "localhost,127.0.0.1,.internal.example"
```

Cuando añadimos el host del registro público a `noproxy` (y, en una segunda ejecución, a `NO_PROXY`), npm se conectó directamente y el proxy no anotó nada. La clave `noproxy` toma por defecto el valor de `NO_PROXY`, así que mantén una sola lista, no dos distintas.

## Errores comunes del proxy de npm y cómo resolverlos

Estos son los mensajes que npm 11 mostró en nuestras pruebas, más dos que no reprodujimos:

- **`npm error code E407` con `407 Proxy Authentication Required`.** El proxy quiere un inicio de sesión y no recibió ninguno, o recibió uno incorrecto. Una contraseña ausente y una contraseña errónea produjeron el mismo texto. Revisa el usuario, la codificación de los caracteres especiales y, si dependes de ella, si tu IP está en la lista de IP autorizadas.
- **`getaddrinfo ENOTFOUND` seguido de un nombre de host extraño.** La URL del proxy se interpretó mal, casi siempre por una `@` o un `#` sin codificar en la contraseña. Si el host nombrado es el propio proxy, revisa cómo está escrito y tu DNS.
- **`connect ECONNREFUSED <proxy-ip>:<port>`.** Nada escucha en ese puerto: un número de puerto equivocado, o el proxy está caído.
- **`connect ETIMEDOUT <ip>:<port>`.** Los paquetes no llegan a ninguna parte; nuestra dirección de prueba inalcanzable falló tras unos 22 segundos. Si hay un proxy definido, su dirección está mal; si no hay ninguno, probablemente la red solo deja salir el tráfico a través de un proxy.
- **`ECONNRESET`.** La conexión se abrió y luego se cortó, normalmente por un proxy que cierra las descargas largas o por un antivirus que inspecciona el tráfico. `--loglevel verbose` muestra qué petición falló.
- **`UNABLE_TO_GET_ISSUER_CERT_LOCALLY` o `SELF_SIGNED_CERT_IN_CHAIN`.** Un proxy de empresa inspecciona el HTTPS y lo vuelve a firmar con su propio certificado raíz, en el que Node.js no confía. Guarda ese certificado raíz en un archivo y apunta a él el ajuste `cafile` de npm o la variable `NODE_EXTRA_CA_CERTS`; la diferencia entre ambos, y cómo encontrar el certificado correcto, la explicamos en nuestra [guía sobre el error del certificado del emisor local](/es/blog/unable-to-get-local-issuer-certificate).

`strict-ssl=false` hace desaparecer el último error desactivando la comprobación de certificados para el registro. Úsalo como mucho durante un minuto de depuración, nunca como solución: con él, cualquiera en el camino de red puede entregarle a npm un paquete modificado.

Otra trampa nos hizo perder tiempo. Con la caché llena, `npm view` imprimió una versión aunque nada escuchaba en el puerto del proxy; npm respondió desde su caché. Solo con la caché vacía apareció `ECONNREFUSED`. Si un cambio de proxy parece funcionar, prueba con un paquete que nunca hayas instalado, o con `--prefer-online` y una carpeta de caché nueva mediante `--cache`.

## ¿Usan Yarn y pnpm los mismos ajustes?

pnpm lee las mismas claves de `.npmrc`, mientras que Yarn 2 y posteriores usan su propio archivo. Los [ajustes de red de pnpm](https://pnpm.io/settings/network) describen `https-proxy`, `http-proxy` y `noproxy`, con la clave antigua `proxy` de npm como alternativa para ambas y, después, las variables `HTTPS_PROXY`, `HTTP_PROXY` y `NO_PROXY`. pnpm solo lee de `.npmrc` los ajustes de autenticación, registro, TLS, proxy y `local-address`, así que una configuración de proxy de npm existente suele funcionar sin cambios.

Yarn 2 y posteriores (Yarn Berry) guardan sus ajustes en `.yarnrc.yml`, con las claves `httpProxy` y `httpsProxy`, que se definen por ejemplo con `yarn config set httpsProxy http://user:pass@pr.proxynet.io:8000`. Su opción de certificado es `httpsCaFilePath`, y `enableStrictSsl` vale `true` por defecto, según la [referencia de configuración de Yarn](https://yarnpkg.com/configuration/yarnrc).

## ¿Llega el proxy a los scripts de instalación y al propio Node.js?

Solo en parte. npm pasa sus ajustes a los scripts de los paquetes como variables de entorno: en nuestra prueba, un script lanzado con `npm run` vio `npm_config_https_proxy` y `npm_config_noproxy`. Que un script las use depende de su autor, así que un paquete que descarga un binario durante la instalación puede fallar igualmente detrás de un proxy. Cuando ocurre, la documentación del propio paquete suele indicar la variable que lee.

Tu propio código Node.js es otro asunto. El `fetch` integrado de Node.js ignora `HTTPS_PROXY` salvo que el proceso arranque con `NODE_USE_ENV_PROXY=1` o con la opción `--use-env-proxy`, que admiten las versiones actuales de Node.js; las opciones de cada biblioteca están en [Cómo usar un proxy en Node.js](/es/blog/nodejs-proxy).

Las dependencias que se instalan directamente desde un repositorio Git (una dirección `git+https://` en `package.json`) las descarga Git, no el código de red de npm. Git tiene sus propios ajustes de proxy, descritos en [Configuración de proxy en Git](/es/blog/git-proxy-settings).

## ¿Cuándo ayuda una IP de proxy fija?

Una IP de salida fija ayuda cuando es el registro, y no tu red, quien decide quién puede conectarse. Los registros autoalojados y los espejos de paquetes suelen estar protegidos por una regla de firewall que permite una lista corta de direcciones de origen. Los agentes de compilación en la nube reciben una dirección nueva en cada ejecución, así que la regla nunca coincide. Si npm pasa por un proxy con una dirección dedicada que no cambia, el firewall solo necesita una entrada.

Los [Proxies de centro de datos](https://proxynet.io/es/datacenter-proxy) mantienen la misma IP dedicada mientras la conserves, algo que encaja con los servidores de compilación.

Los [Proxies ISP](https://proxynet.io/es/static-isp-residential-proxy) hacen lo mismo con una dirección registrada a nombre de un proveedor de internet. Ambos se venden por IP y vienen por defecto con una restricción de sitios de destino; comprueba que el host de tu registro esté cubierto o añade la opción «Acceso a todos los sitios web». Detrás de un proxy corporativo nada de esto aplica: usa la dirección que te dé tu equipo de TI.

## Guía de decisión

| Necesidad | Ajuste |
|---|---|
| Cada instalación en tu máquina | `npm config set proxy` y `https-proxy` |
| Solo un proyecto | `--location=project`, sin contraseña dentro |
| Trabajo de CI o contenedor | `HTTPS_PROXY` más `HTTP_PROXY` y `NO_PROXY` |
| Un solo comando | Opción `--https-proxy` |
| Acceso directo al registro interno | `noproxy` con su dominio |
| Contraseña con `@` o `#` | Codificación porcentual |
| Contraseña fuera de los archivos | `${VAR}` en `.npmrc` o lista de IP autorizadas |
| Proxy de empresa con inspección TLS | `cafile` o `NODE_EXTRA_CA_CERTS` |
| Registro que solo admite IP permitidas | Proxy con IP dedicada |

## Preguntas frecuentes

### ¿Cómo configuro un proxy en npm?

Ejecuta `npm config set proxy http://host:port` y `npm config set https-proxy http://host:port`, y añade `user:pass@` delante del host si el proxy pide inicio de sesión. Los ajustes van a tu `.npmrc` de usuario y se aplican desde ese momento a cada comando de npm.

### ¿Cómo configuro un proxy de npm con usuario y contraseña?

Ponlos en la URL como `http://user:password@host:port` y codifica los caracteres especiales de ambas partes: `@` pasa a `%40`, `:` a `%3A` y `#` a `%23`. Una `@` sin codificar hace que npm lea el resto de la contraseña como nombre del host y falle con `ENOTFOUND`.

### ¿Cómo quito el proxy de npm?

Ejecuta `npm config delete proxy` y `npm config delete https-proxy`, y luego comprueba con `npm config list`. Si el tráfico sigue pasando por un proxy, busca `HTTPS_PROXY` o `npm_config_https_proxy` en tu entorno y un `.npmrc` de proyecto o global.

### ¿Dónde se guarda la configuración de proxy de npm?

En un archivo `.npmrc`: por usuario en tu carpeta personal de forma predeterminada, por proyecto junto a `package.json` o de forma global bajo el prefijo de npm. `npm config list` imprime la ruta de cada archivo leído encima de los ajustes que vienen de él.

### ¿Usa npm el proxy del sistema en Windows?

No. npm solo lee sus propios ajustes y las variables de entorno, no el proxy configurado en los ajustes de red de Windows ni en Opciones de Internet. Define la misma dirección con `npm config set` o con `HTTPS_PROXY`.

### ¿Puede npm usar un proxy SOCKS5?

La capa de red de npm incluye un cliente SOCKS y acepta direcciones como `socks5://host:port` en los ajustes de proxy, según muestra el código fuente de npm 11; no lo probamos contra un servidor SOCKS real. Si falla en tu versión, usa el endpoint HTTP del proveedor, que es la vía que usaron todas las pruebas de esta guía.

## En resumen

Dale un proxy a npm con `npm config set proxy` y `npm config set https-proxy`, o con `HTTPS_PROXY` en shells y CI; `HTTP_PROXY` sola no desvió el tráfico del registro en nuestra prueba. Los ajustes de la línea de comandos se imponen a las variables `npm_config_*`, y estas a los archivos `.npmrc` de proyecto, de usuario y global. Codifica los caracteres especiales de la contraseña, mantén los hosts internos en `noproxy`, comprueba con `npm config list` y quita las dos claves con `npm config delete`. Los errores de certificado detrás de un proxy de empresa necesitan el certificado raíz de la empresa, no `strict-ssl=false`. Los endpoints de proxy que funcionan con todos estos ajustes están en la [página de proxies de Proxynet](/es/proxy).
