# proxy-agent

> Maps proxy protocols to `http.Agent` implementations

Latest version **8.0.2** (published 2026-06-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install proxy-agent
pnpm add proxy-agent
yarn add proxy-agent
bun add proxy-agent
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 8.0.2 |
| Published | 2026-06-08 |
| First published | 2013-11-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >= 20 |
| Dependencies | 8 |
| Unpacked size | 17 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1163 |
| Author | Nathan Rajlich |
| Maintainers | tootallnate |
| Keywords | http, https, socks, agent, mapping, proxy |

## Links

- npm: https://www.npmjs.com/package/proxy-agent
- Repository: https://github.com/TooTallNate/proxy-agents
- Homepage: https://github.com/TooTallNate/proxy-agents#readme
- Issues: https://github.com/TooTallNate/proxy-agents/issues
- npm.io page: https://npm.io/package/proxy-agent

## Dependencies (8)

- [debug](https://npm.io/package/debug.md) ^4.3.4
- [lru-cache](https://npm.io/package/lru-cache.md) ^7.14.1
- [agent-base](https://npm.io/package/agent-base.md) 9.0.0
- [proxy-from-env](https://npm.io/package/proxy-from-env.md) ^2.0.0
- [pac-proxy-agent](https://npm.io/package/pac-proxy-agent.md) 9.1.0
- [http-proxy-agent](https://npm.io/package/http-proxy-agent.md) 9.1.0
- [https-proxy-agent](https://npm.io/package/https-proxy-agent.md) 9.1.0
- [socks-proxy-agent](https://npm.io/package/socks-proxy-agent.md) 10.1.0

## Recent versions

- 8.0.2 (latest) — 2026-06-08
- 8.0.1 — 2026-04-06
- 8.0.0 — 2026-04-01
- 7.0.0 — 2026-03-11
- 6.5.0 — 2024-12-07
- 6.4.0 — 2024-02-12
- 6.3.1 — 2023-09-04
- 6.3.0 — 2023-07-18
- 6.2.2 — 2023-07-13
- 6.2.1 — 2023-05-25
- 6.2.0 — 2023-05-09
- 6.1.2 — 2023-05-05
- 6.1.1 — 2023-05-04
- 6.1.0 — 2023-05-04
- 6.0.0 — 2023-05-04
- … 18 more at https://npm.io/package/proxy-agent/versions

## README

proxy-agent
===========
### Maps proxy protocols to `http.Agent` implementations

This module provides an `http.Agent` implementation which automatically uses
proxy servers based off of the various proxy-related environment variables
(`HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` among others).

Which proxy is used for each HTTP request is determined by the
[`proxy-from-env`](https://www.npmjs.com/package/proxy-from-env) module, so
check its documentation for instructions on configuring your environment variables.

An LRU cache is used so that `http.Agent` instances are transparently re-used for
subsequent HTTP requests to the same proxy server.

The currently implemented protocol mappings are listed in the table below:


| Protocol   | Proxy Agent for `http` requests | Proxy Agent for `https` requests | Example
|:----------:|:-------------------------------:|:--------------------------------:|:--------:
| `http`     | [http-proxy-agent][]            | [https-proxy-agent][]            | `http://proxy-server-over-tcp.com:3128`
| `https`    | [http-proxy-agent][]            | [https-proxy-agent][]            | `https://proxy-server-over-tls.com:3129`
| `socks(v5)`| [socks-proxy-agent][]           | [socks-proxy-agent][]            | `socks://username:password@some-socks-proxy.com:9050` (username & password are optional)
| `socks5`   | [socks-proxy-agent][]           | [socks-proxy-agent][]            | `socks5://username:password@some-socks-proxy.com:9050` (username & password are optional)
| `socks4`   | [socks-proxy-agent][]           | [socks-proxy-agent][]            | `socks4://some-socks-proxy.com:9050`
| `pac-*`    | [pac-proxy-agent][]             | [pac-proxy-agent][]              | `pac+http://www.example.com/proxy.pac`

Example
-------

```ts
import * as https from 'https';
import { ProxyAgent } from 'proxy-agent';

// The correct proxy `Agent` implementation to use will be determined
// via the `http_proxy` / `https_proxy` / `no_proxy` / etc. env vars
const agent = new ProxyAgent();

// The rest works just like any other normal HTTP request
https.get('https://jsonip.com', { agent }, (res) => {
  console.log(res.statusCode, res.headers);
  res.pipe(process.stdout);
});
```


API
---

### new ProxyAgent(options?: ProxyAgentOptions)

Creates an `http.Agent` instance which relies on the various proxy-related
environment variables. An LRU cache is used, so the same `http.Agent` instance
will be returned if identical args are passed in.

[http-proxy-agent]: ../http-proxy-agent
[https-proxy-agent]: ../https-proxy-agent
[socks-proxy-agent]: ../socks-proxy-agent
[pac-proxy-agent]: ../pac-proxy-agent

---
_Source: https://npm.io/package/proxy-agent · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._