---
title: "Proxy no npm: como configurar o npm atrás de um proxy"
description: "Configure o proxy do npm com npm config set proxy e https-proxy, ou com HTTPS_PROXY. Ordem dos .npmrc, senhas com caracteres especiais, noproxy e erros."
url: https://proxynet.io/pt-br/blog/npm-proxy-settings
date: 2026-11-19
author: "Acar Diveroli"
category: "Tutoriais"
lang: pt-BR
---

# Proxy no npm: como configurar o npm atrás de um proxy

Você abre um projeto em um notebook novo do trabalho, roda `npm install` e nada acontece por vinte segundos. Então aparece `npm error code ETIMEDOUT`, seguido de uma dica de que você talvez esteja atrás de um proxy. O registry abre normalmente no navegador da mesma máquina, porque o navegador usa o proxy da empresa que o Windows ou o macOS repassa a ele. O npm não lê essas configurações do sistema. Ele precisa das próprias.

Este guia mostra as três formas de dar um proxy ao npm (`npm config`, arquivos `.npmrc` e variáveis de ambiente), a ordem em que o npm as lê, senhas com caracteres especiais, como conferir e remover as configurações, como deixar hosts internos fora do proxy e os erros mais comuns. Rodamos cada comando no Windows 11 com Node.js 24.22.2 e npm 11.19.1, contra um proxy local que anotava cada requisição e pedia senha, sempre com um arquivo de configuração descartável.

> **Nota: Resposta rápida**
>
> Rode `npm config set proxy http://user:pass@pr.proxynet.io:8000` e `npm config set https-proxy http://user:pass@pr.proxynet.io:8000`. As duas linhas vão para o seu `.npmrc` de usuário e valem para todo `npm install` seguinte. Codifique os caracteres especiais da senha (`@` como `%40`, `:` como `%3A`, `#` como `%23`), liste os hosts internos em `noproxy` e confira o resultado com `npm config list`, que esconde a senha. Em vez do arquivo de configuração, você pode definir `HTTPS_PROXY`; o npm a lê para o registry, enquanto `HTTP_PROXY` sozinha não desviou o nosso tráfego para o registry. Remova as configurações com `npm config delete proxy` e `npm config delete https-proxy`.

## Quando o npm precisa de um proxy?

O npm precisa de um proxy sempre que a máquina não consegue chegar ao registry diretamente, ou precisa chegar a ele a partir de um endereço conhecido. O registry é o servidor que hospeda os pacotes; para a maioria dos projetos ele é `https://registry.npmjs.org`, mas uma empresa pode ter o seu próprio.

Duas situações cobrem quase todos os casos. Uma rede corporativa só deixa o tráfego sair por um proxy, e por isso uma conexão direta com o registry entra em timeout. Ou um registry privado aceita requisições apenas de endereços IP liberados, e o seu notebook ou runner de CI não tem um IP fixo. Nos dois casos, é preciso dizer ao npm onde está o proxy, porque ele não aproveita as configurações de proxy do sistema operacional como um navegador faz.

## Como o npm envia uma requisição por um proxy?

O npm fala primeiro com o proxy e pede que ele abra um túnel até o registry. Os passos abaixo são o que o nosso proxy de teste anotou durante `npm view semver version`:

1. **O npm escolhe um endereço de proxy.** Ele usa `https-proxy`, se estiver definido, e senão `proxy`. Só quando os dois estão vazios ele olha a variável de ambiente `HTTPS_PROXY`.
2. **O npm confere a lista de exclusão.** Se o host do registry corresponder a uma entrada de `noproxy` (ou `NO_PROXY`), o proxy é ignorado e o npm se conecta diretamente.
3. **O npm abre uma conexão TCP com o proxy e envia `CONNECT registry.npmjs.org:443`.** Se o endereço do proxy tiver usuário e senha, o npm os manda em um cabeçalho `Proxy-Authorization` já nessa primeira requisição. O nosso log não mostrou nenhuma ida e volta extra: `CONNECT registry.npmjs.org:443 auth user=user (ok)`.
4. **O proxy responde `200 Connection Established`** e daí em diante só repassa bytes. O handshake TLS acontece entre o npm e o registry dentro do túnel, então o proxy vê o nome do host e a porta, não os pacotes.
5. **O npm baixa os metadados e os tarballs** e os guarda no cache local, o que importa mais tarde na hora de depurar.

## Como configurar o proxy do npm?

Dois comandos `npm config set` configuram o proxy para a sua conta de usuário:

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

O npm grava os dois no arquivo `.npmrc` do usuário (`~/.npmrc` no macOS e no Linux, `C:\Users\<name>\.npmrc` no Windows). Na nossa máquina de teste, o arquivo ficou depois com exatamente estas linhas:

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

Repare que `https-proxy` também começa com `http://`. O esquema descreve a conexão com o proxy, não com o registry: o proxy recebe HTTP simples do npm e leva o tráfego HTTPS dentro do túnel `CONNECT`. Escreva `https://` apenas se o próprio proxy esperar TLS nessa porta.

Defina as duas chaves. No nosso teste, `proxy` sozinha bastou para o registry HTTPS, porque o npm recorre a ela quando `https-proxy` está vazia, mas nem toda ferramenta que lê as configurações do npm aplica a mesma alternativa. O npm rejeita chaves desconhecidas, então um erro de digitação como `npm config set proxi …` termina com ``npm error `proxi` is not a valid npm option``.

Se a máquina tiver um IP fixo, a whitelist de IP da Proxynet permite deixar as credenciais fora da URL: nesse caso, `http://pr.proxynet.io:8000` é a configuração inteira.

## Quais configurações o npm lê, e em que ordem?

O npm junta configurações de várias fontes, e a mais específica vence. A [documentação de configuração do npm](https://docs.npmjs.com/cli/v11/using-npm/config) define a prioridade assim: primeiro as opções da linha de comando, depois as variáveis de ambiente que começam com `npm_config_`, em seguida os arquivos `.npmrc` e, por último, os padrões embutidos.

| Fonte | Exemplo | Alcance |
|---|---|---|
| Opção da linha de comando | `--https-proxy http://…` | Um comando |
| Variável `npm_config_*` | `npm_config_https_proxy` | O shell atual |
| `.npmrc` do projeto | `<project>/.npmrc` | Aquele projeto |
| `.npmrc` do usuário | `~/.npmrc` | A sua conta |
| `npmrc` global | `$PREFIX/etc/npmrc` | Todos os usuários daquele Node.js |
| `npmrc` embutido | na pasta de instalação do npm | Aquela cópia do npm |

Conferimos a ordem com um arquivo descartável: `npm_config_proxy=http://env.example:3128` prevaleceu sobre o arquivo do usuário, e `--proxy http://cli.example:3128` prevaleceu sobre os dois. Os nomes das variáveis de ambiente não diferenciam maiúsculas de minúsculas, e os hifens viram sublinhados, então a chave `https-proxy` vira `npm_config_https_proxy`.

A opção `--location` de `npm config set` escolhe o arquivo: `user` é o padrão, `project` grava o `.npmrc` ao lado do seu `package.json` e `global` grava o arquivo sob o prefixo do npm. Um `.npmrc` de projeto é prático quando só um repositório precisa do proxy, mas ele costuma ir para o controle de versão, então não coloque senhas nele. A [referência do .npmrc](https://docs.npmjs.com/cli/v11/configuring-npm/npmrc) também documenta a substituição `${VARIABLE_NAME}`: uma linha como `https-proxy=${NPM_PROXY_URL}` lê a URL completa do proxy de uma variável de ambiente quando o npm inicia, o que mantém o segredo fora do arquivo. Testamos; com a variável não definida, o npm deixou no lugar o texto literal `${NPM_PROXY_URL}`.

## HTTP_PROXY e HTTPS_PROXY funcionam com o npm?

`HTTPS_PROXY` funciona; `HTTP_PROXY` sozinha não desviou o tráfego do registry no nosso teste. Com `HTTPS_PROXY` definida e nenhum proxy em nenhum `.npmrc`, toda requisição ao registry passou pelo nosso proxy. Só com `HTTP_PROXY`, o `npm view` se conectou diretamente e o log do proxy ficou vazio, embora a própria descrição de `https-proxy` no npm cite `HTTP_PROXY` como alternativa. O código do npm 11.19.1 lê apenas `HTTPS_PROXY` para endereços `https://`, e o registry público funciona sobre HTTPS.

O padrão seguro para um shell, um contêiner ou um job de CI é definir as duas, mais as exclusões:

```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"
```

No Windows PowerShell, as mesmas linhas ficam `$env:HTTPS_PROXY = "http://user:pass@pr.proxynet.io:8000"` e assim por diante. Uma armadilha: `npm config get https-proxy` imprime `null` mesmo com `HTTPS_PROXY` definida, porque o npm só aplica a variável no momento em que envia uma requisição. Não leia esse `null` como "sem proxy".

## Como colocar usuário e senha na URL do proxy?

Escreva os dois antes do host como `user:password@` e aplique codificação percentual a todo caractere que tenha significado em uma URL. A codificação percentual troca um caractere por `%` e o seu código hexadecimal. Os caracteres que quebram uma URL de proxy são os delimitadores listados na [RFC 3986, seção 2.2](https://www.rfc-editor.org/rfc/rfc3986.html#section-2.2): `:`, `/`, `?`, `#`, `[`, `]` e `@`. Um espaço e o próprio `%` também precisam ser codificados.

| Caractere | Codificado |
|---|---|
| `@` | `%40` |
| `:` | `%3A` |
| `#` | `%23` |
| `/` | `%2F` |
| `%` | `%25` |
| espaço | `%20` |

O nosso proxy de teste aceitava a senha `p@ss:w#rd`. Escrita sem codificar, como `http://user:p@ss:w#rd@127.0.0.1:18080`, o npm nem chegou ao proxy: o Node.js avisou que a URL era inválida, e o npm parou com `getaddrinfo ENOTFOUND ss`. Ele tinha lido o texto depois do primeiro `@` como nome do host. Codificada como `http://user:p%40ss%3Aw%23rd@127.0.0.1:18080`, o mesmo comando retornou a versão do pacote, e o proxy anotou um login correto. Se um erro de DNS citar um host que você nunca digitou, olhe primeiro para a senha.

## Como conferir e remover as configurações de proxy do npm?

`npm config list` mostra cada configuração diferente do padrão e o arquivo de onde ela veio. Na nossa execução, a saída começava com uma linha que nomeava a origem, `; "user" config from …\test.npmrc`, seguida de `proxy = "http://user:***@pr.proxynet.io:8000"`. O npm mascara a senha nessa visualização, o que torna a saída segura para colar em um chamado de suporte.

`npm config get proxy` se recusa a imprimir um valor que contenha senha: `The proxy option is protected, and cannot be retrieved in this way`. Sem credenciais na URL, ele imprime o endereço como está gravado; `npm config edit` abre o próprio arquivo.

Para remover o proxy, apague as duas chaves:

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

Cada `delete` remove uma linha de um arquivo; no nosso teste, a linha `https-proxy` continuou lá até ser apagada separadamente. Acrescente `--location=project` ou `--location=global` para os outros arquivos, e confira `HTTPS_PROXY` e `npm_config_https_proxy` no seu shell, porque uma variável esquecida continua desviando o tráfego depois que o arquivo está limpo. Para pular o proxy em um único comando sem mexer no arquivo, passe o host do registry como exclusão: `--noproxy registry.npmjs.org`.

## Como deixar alguns hosts fora do proxy?

Liste-os em `noproxy`, separados por vírgulas. O npm compara o nome do host segmento por segmento a partir da direita, então `.internal.example` corresponde a `registry.internal.example` e a qualquer outro nome sob esse domínio.

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

Quando adicionamos o host do registry público a `noproxy` (e, em uma segunda execução, a `NO_PROXY`), o npm se conectou diretamente e o proxy não anotou nada. A chave `noproxy` assume por padrão o valor de `NO_PROXY`, então mantenha uma lista só, e não duas diferentes.

## Erros comuns de proxy no npm e como corrigir

Estas são as mensagens que o npm 11 mostrou nos nossos testes, mais duas que não reproduzimos:

- **`npm error code E407` com `407 Proxy Authentication Required`.** O proxy quer um login e não recebeu nenhum, ou recebeu um errado. Uma senha ausente e uma senha errada produziram o mesmo texto. Confira o usuário, a codificação dos caracteres especiais e, se você depende dela, se o seu IP está na whitelist.
- **`getaddrinfo ENOTFOUND` seguido de um nome de host estranho.** A URL do proxy foi interpretada errado, quase sempre por causa de um `@` ou `#` sem codificar na senha. Se o host citado for o próprio proxy, confira a grafia e o seu DNS.
- **`connect ECONNREFUSED <proxy-ip>:<port>`.** Nada escuta nessa porta: um número de porta errado, ou o proxy está fora do ar.
- **`connect ETIMEDOUT <ip>:<port>`.** Os pacotes não chegam a lugar nenhum; o nosso endereço de teste inalcançável falhou depois de cerca de 22 segundos. Com um proxy definido, o endereço dele está errado; sem nenhum, a rede provavelmente só deixa o tráfego sair por um proxy.
- **`ECONNRESET`.** A conexão foi aberta e depois cortada, normalmente por um proxy que encerra downloads longos ou por um antivírus que inspeciona o tráfego. `--loglevel verbose` mostra qual requisição falhou.
- **`UNABLE_TO_GET_ISSUER_CERT_LOCALLY` ou `SELF_SIGNED_CERT_IN_CHAIN`.** Um proxy corporativo inspeciona o HTTPS e o assina de novo com o seu próprio certificado raiz, no qual o Node.js não confia. Coloque esse certificado raiz em um arquivo e aponte para ele a configuração `cafile` do npm ou a variável `NODE_EXTRA_CA_CERTS`; a diferença entre as duas, e como achar o certificado certo, está no nosso [guia sobre o erro do certificado do emissor local](/pt-br/blog/unable-to-get-local-issuer-certificate).

`strict-ssl=false` faz o último erro sumir desligando a verificação de certificados para o registry. Use no máximo por um minuto de depuração, nunca como correção: com ele, qualquer um no caminho da rede pode entregar ao npm um pacote modificado.

Mais uma armadilha nos custou tempo. Com o cache preenchido, o `npm view` imprimiu uma versão mesmo sem nada escutando na porta do proxy; o npm respondeu a partir do cache. Só com o cache vazio apareceu `ECONNREFUSED`. Se uma mudança de proxy parecer funcionar, teste com um pacote que você nunca instalou, ou com `--prefer-online` e uma pasta de cache nova via `--cache`.

## Yarn e pnpm usam as mesmas configurações?

O pnpm lê as mesmas chaves do `.npmrc`, enquanto o Yarn 2 e versões posteriores usam um arquivo próprio. As [configurações de rede do pnpm](https://pnpm.io/settings/network) descrevem `https-proxy`, `http-proxy` e `noproxy`, com a chave antiga `proxy` do npm como alternativa para as duas e, depois disso, as variáveis `HTTPS_PROXY`, `HTTP_PROXY` e `NO_PROXY`. O pnpm lê do `.npmrc` apenas as configurações de autenticação, registry, TLS, proxy e `local-address`, então uma configuração de proxy do npm já existente costuma funcionar sem mudanças.

O Yarn 2 e versões posteriores (Yarn Berry) guardam as configurações em `.yarnrc.yml`, com as chaves `httpProxy` e `httpsProxy`, definidas por exemplo com `yarn config set httpsProxy http://user:pass@pr.proxynet.io:8000`. A opção de certificado é `httpsCaFilePath`, e `enableStrictSsl` vem como `true` por padrão, segundo a [referência de configuração do Yarn](https://yarnpkg.com/configuration/yarnrc).

## O proxy chega aos scripts de instalação e ao próprio Node.js?

Só em parte. O npm passa as configurações para os scripts dos pacotes como variáveis de ambiente: no nosso teste, um script iniciado com `npm run` enxergou `npm_config_https_proxy` e `npm_config_noproxy`. Se um script as usa ou não, depende do autor, então um pacote que baixa um binário durante a instalação ainda pode falhar atrás de um proxy. Quando isso acontece, a documentação do próprio pacote costuma indicar a variável que ele lê.

O seu próprio código Node.js é outra história. O `fetch` embutido do Node.js ignora `HTTPS_PROXY`, a menos que o processo inicie com `NODE_USE_ENV_PROXY=1` ou com a opção `--use-env-proxy`, que as versões atuais do Node.js suportam; as opções de cada biblioteca estão em [Como usar proxy no Node.js](/pt-br/blog/nodejs-proxy).

Dependências instaladas direto de um repositório Git (um endereço `git+https://` no `package.json`) são baixadas pelo Git, não pelo código de rede do npm. O Git tem as próprias configurações de proxy, descritas em [Configurar proxy no Git: como usar o Git atrás de um proxy](/pt-br/blog/git-proxy-settings).

## Quando um IP de proxy fixo ajuda?

Um IP de saída fixo ajuda quando é o registry, e não a sua rede, que decide quem pode se conectar. Registries auto-hospedados e espelhos de pacotes costumam ser protegidos por uma regra de firewall que libera uma lista curta de endereços de origem. Agentes de build na nuvem recebem um endereço novo a cada execução, então a regra nunca bate. Passar o npm por um proxy com um endereço dedicado e imutável dá ao firewall uma única entrada para liberar.

Os [Proxies de datacenter](https://proxynet.io/pt-br/datacenter-proxy) mantêm o mesmo IP dedicado enquanto você o mantiver, o que combina com servidores de build.

Os [Proxies ISP](https://proxynet.io/pt-br/static-isp-residential-proxy) fazem o mesmo com um endereço registrado em nome de um provedor de internet. Os dois são vendidos por IP e vêm por padrão com uma restrição de site de destino; confira se o host do seu registry está coberto ou adicione a opção "Acesso a todos os sites". Atrás de um proxy corporativo, nada disso se aplica: use o endereço que a sua equipe de TI passar.

## Guia de decisão

| Necessidade | Configuração |
|---|---|
| Toda instalação na sua máquina | `npm config set proxy` e `https-proxy` |
| Só um projeto | `--location=project`, sem senha nele |
| Job de CI ou contêiner | `HTTPS_PROXY` mais `HTTP_PROXY` e `NO_PROXY` |
| Um único comando | Opção `--https-proxy` |
| Acesso direto ao registry interno | `noproxy` com o domínio dele |
| Senha com `@` ou `#` | Codificação percentual |
| Senha fora dos arquivos | `${VAR}` no `.npmrc` ou whitelist de IP |
| Proxy corporativo com inspeção TLS | `cafile` ou `NODE_EXTRA_CA_CERTS` |
| Registry que só libera IPs da lista | Proxy com IP dedicado |

## Perguntas frequentes

### Como configurar um proxy no npm?

Rode `npm config set proxy http://host:port` e `npm config set https-proxy http://host:port`, acrescentando `user:pass@` antes do host se o proxy pedir login. As configurações vão para o seu `.npmrc` de usuário e valem a partir daí para todo comando do npm.

### Como configurar um proxy no npm com usuário e senha?

Coloque os dois na URL como `http://user:password@host:port` e codifique os caracteres especiais das duas partes: `@` vira `%40`, `:` vira `%3A` e `#` vira `%23`. Um `@` sem codificar faz o npm ler o resto da senha como nome do host e falhar com `ENOTFOUND`.

### Como remover o proxy do npm?

Rode `npm config delete proxy` e `npm config delete https-proxy` e depois confira com `npm config list`. Se o tráfego ainda passar por um proxy, procure `HTTPS_PROXY` ou `npm_config_https_proxy` no seu ambiente e um `.npmrc` de projeto ou global.

### Onde fica a configuração de proxy do npm?

Em um arquivo `.npmrc`: por padrão, por usuário na sua pasta pessoal; por projeto, ao lado do `package.json`; ou de forma global, sob o prefixo do npm. `npm config list` imprime o caminho de cada arquivo lido acima das configurações que vieram dele.

### O npm usa o proxy do sistema no Windows?

Não. O npm lê apenas as próprias configurações e as variáveis de ambiente, não o proxy definido nas configurações de rede do Windows nem nas Opções da Internet. Defina o mesmo endereço com `npm config set` ou `HTTPS_PROXY`.

### O npm pode usar um proxy SOCKS5?

A camada de rede do npm inclui um cliente SOCKS e aceita endereços como `socks5://host:port` nas configurações de proxy, como mostra o código-fonte do npm 11; não testamos isso contra um servidor SOCKS real. Se falhar na sua versão, use o endpoint HTTP do provedor, que foi o caminho usado em todos os testes deste guia.

## Em resumo

Dê um proxy ao npm com `npm config set proxy` e `npm config set https-proxy`, ou com `HTTPS_PROXY` em shells e CI; `HTTP_PROXY` sozinha não desviou o tráfego do registry no nosso teste. Configurações na linha de comando prevalecem sobre as variáveis `npm_config_*`, que prevalecem sobre os arquivos `.npmrc` de projeto, de usuário e global. Codifique os caracteres especiais da senha, mantenha os hosts internos em `noproxy`, confira com `npm config list` e remova as duas chaves com `npm config delete`. Erros de certificado atrás de um proxy corporativo pedem o certificado raiz da empresa, não `strict-ssl=false`. Os endpoints de proxy que funcionam com todas essas configurações estão na [página de proxies da Proxynet](/pt-br/proxy).
