Axios is one of the most popular HTTP clients for JavaScript. Developers use it for APIs, backend services, web automation, and any project requiring making an axios request.
To use a proxy with axios, you first need to import axios in your project.
When working with network restrictions, privacy requirements, or large-scale scraping, you may need to route requests through a proxy. This guide explains how to use a proxy with axios, including how to set up HTTP, HTTPS, and SOCKS proxies.
How Proxy Support Works in Axios
Axios supports proxies through its request configuration object, where you specify the proxy using a proxy object within the request config. When you specify a proxy object, Axios sends the request through that proxy server instead of directly to the target URL.
A basic proxy setup in Axios looks like this:
axios.get("https://example.com", {
proxy: {
host: "127.0.0.1",
port: 8080
}
});
In this example, the request config includes various request options, such as the proxy object, to customize the request behavior. For simple GET requests, only the url is required, but you can provide additional request options in the request config as needed.
Axios uses the HTTP CONNECT method for HTTPS requests and standard forwarding for HTTP requests. This makes it suitable for typical HTTP proxies used in Node.js environments.
Setting an HTTP Proxy in Axios
The simplest axios proxy configuration requires only a host and port:
const axios = require("axios");
axios.get("https://example.com", {
proxy: {
host: "192.168.1.10",
port: 8000
}
});
This sends all traffic through the given proxy server.
If the proxy requires authentication, you can pass the username and password in an auth object:
axios.get("https://example.com", {
proxy: {
host: "192.168.1.10",
port: 8000,
auth: {
username: "user123",
password: "mypassword"
}
}
});
Private proxies often require an auth object containing your credentials to access the proxy server securely.
Axios will include the proper Proxy-Authorization header automatically.
Disabling Axios Proxy Behavior
By default, Axios automatically reads HTTP_PROXY and HTTPS_PROXY environment variables. If you need to turn off proxy usage for a specific request, you can disable the proxy option:
axios.get("https://example.com", {
proxy: false
});
This forces Axios to send the request directly, ignoring environment variables.
Using HTTPS Proxies with Axios
HTTPS proxies work the same way as standard HTTP proxies in Axios. You specify the host, port, and optional authentication.
axios.get("https://secure-site.com", {
proxy: {
host: "proxy-server.com",
port: 443
}
});
This setup allows you to send an https request through the proxy.
Axios uses the CONNECT method to create a secure tunnel to the destination.
Using SOCKS Proxies with Axios
Axios does not natively support SOCKS5 or SOCKS4 proxies, but you can enable them using a custom agent. One common approach is using the socks-proxy-agent package. When configuring the agent, you may need to specify the proxy protocol (such as socks5 or socks4) in the proxy URL.
Example:
const axios = require("axios");
const SocksProxyAgent = require("socks-proxy-agent");
const agent = new SocksProxyAgent("socks5://127.0.0.1:1080");
axios.get("https://example.com", {
httpAgent: agent,
httpsAgent: agent,
proxy: false
});
You can obtain SOCKS proxies from a proxy provider, which often offers features like IP rotation and geo-targeting.
Important points:
- Set proxy to false so Axios does not override the custom agent
- Provide the agent for both httpAgent and httpsAgent
This allows Axios to send traffic through SOCKS proxies.
Using a Global Proxy in Axios
For large applications, you may want a default proxy configuration applied to all requests:
const axios = require("axios");
axios.defaults.proxy = {
host: "proxy.example.com",
port: 8080
};
axios.get("https://example.com");
axios.post("https://example.com/data");
This global proxy configuration applies to all request methods, including GET, POST, and others. You can override or disable the proxy on individual requests if needed.
Using Proxy URLs Instead of Objects
Some developers prefer a single proxy URL string. Axios does not support this format directly, but Node.js libraries like https-proxy-agent make it easy.
Example:
const axios = require("axios");
const HttpsProxyAgent = require("https-proxy-agent");
const agent = new HttpsProxyAgent("http://user:pass@proxy.example.com:8080");
axios.get("https://example.com", {
httpsAgent: agent,
proxy: false
});
You can also include custom headers in the request config when using a custom agent, allowing you to specify authentication tokens or content types as needed.
This approach is more flexible when dealing with complex authentication or when switching between proxy types.
Creating a Proxy List Array
When working with large-scale web scraping, load balancing, or trying to avoid rate limits, using a single proxy server is often not enough. Instead, you can create a proxy list array—a collection of proxy servers, each with its own IP address and port. This approach allows you to distribute your HTTP requests across multiple proxies, reducing the risk of being blocked and improving your scraping efficiency.
A proxy list array is simply an array of objects, where each object contains the proxy details needed for axios requests. Here’s how you can define a basic proxy list array in JavaScript:
const proxyList = [
{ host: "192.168.1.10", port: 8000 },
{ host: "192.168.1.11", port: 8001 },
{ host: "192.168.1.12", port: 8002 }
];
Each entry in the proxy list array represents a different proxy server, complete with its own IP address and proxy port. You can expand this array with additional proxy details, such as authentication credentials, if your proxies require them.
To use these proxies with axios, you can select a proxy from the array for each HTTP request. For example, to rotate proxies and distribute your requests, you might pick a random proxy from the list:
const axios = require("axios");
function getRandomProxy(proxyList) {
return proxyList[Math.floor(Math.random() * proxyList.length)];
}
const proxy = getRandomProxy(proxyList);
axios.get("https://example.com", {
proxy: proxy
});
This setup is especially useful for web scraping projects, as it helps you avoid detection and bypass IP-based rate limits. By maintaining a proxy list array, you can easily manage multiple proxy servers, switch between them, and ensure your HTTP requests are routed efficiently. Whether you’re using free proxies, premium proxies, or a mix of residential and datacenter proxies, organizing your proxy details in an array makes your proxy configuration flexible and scalable.
Handling Proxy Errors in Axios
Common errors include:
- Incorrect proxy settings
- Outdated authentication credentials
- Network connectivity problems
- Proxy server status: Always check the proxy server status to ensure the proxy is operational when experiencing connection issues.
Proxy authentication failures
Check username, password, and any special characters. Encode them when needed.
Connection refused
The proxy server might be unreachable or blocked by a firewall.
Request timeout
Increase the timeout value:
axios.get("https://example.com", {
timeout: 10000,
proxy: {...}
});
HTTPS handshake failures
Often occur with outdated proxy servers or incorrect agents.
Should You Use Axios Proxies
Axios proxies are useful when:
- You need anonymity for scraping or API automation, especially by using residential proxies or a residential proxy service to avoid blocks and bypass geographic restrictions
- Your environment blocks outbound requests
- You need to test API behavior from different locations
- You want to load balance or rotate IPs across requests by using a proxy pool and implementing proxy rotation or rotating proxies to distribute multiple requests and avoid detection
Using a free proxy can be an option for testing purposes, but keep in mind that free proxies often have reliability and security issues.
You can send requests through different proxy IPs and check the proxy's IP, proxy's IP address, or your current IP address in the response data to verify your proxy setup.
In Node.js environments, proxy support is stable and easy to configure. In browsers, Axios cannot use proxies directly because browsers rely on system proxy settings instead of manual configuration.
Summary
Configuring an axios proxy is simple and flexible. You can set per-request proxies, global defaults, authenticated proxies, or even SOCKS proxies through custom agents. Whether you are automating tasks, testing network behavior, or sending large volumes of requests, Axios provides the tools necessary to control how your traffic is routed.
FAQs
