Hype Proxies

How to use a proxy with Puppeteer

This guide walks you through integrating HypeProxies with Puppeteer to bypass IP restrictions, overcome geo-targeting, and manage rate limiting in web scraping workflows.

Speed

Success

Consistency

Reliability

Flexibility

Prerequisites

Before integrating proxies into Puppeteer, make sure your development environment is set up properly.

Puppeteer installation

Puppeteer requires Node.js 18 or higher. If you’re new to Puppeteer, follow the official installation guide to get started with the browser automation library.

Puppeteer homepage mockup

HypeProxies setup

You’ll need active proxy credentials from your HypeProxies dashboard:

  1. Log in to your HypeProxies dashboard (or create an account). New users can also request a 24-hour trial.

  2. Choose the right proxy type for your workflow and purchase a plan that fits your needs – ISP proxies, sneaker proxies, or ticket proxies.

Locate your active proxies in the dashboard, formatted as IP:PORT:USERNAME:PASSWORD.

HypeProxies dashboard

Tip – use the proxy checker tool to verify connectivity before implementation.

Method 1 – browser-wide proxy configuration

The simplest approach routes all browser traffic through a single proxy using Chrome’s --proxy-server flag.

import puppeteer from "puppeteer";

const proxyCredentials = 'YOUR_IP:YOUR_PORT:YOUR_USERNAME:YOUR_PASSWORD';
const [HOST, PORT, USER, PASS] = proxyCredentials.split(":");

const browser = await puppeteer.launch({
  args: [`--proxy-server=http://${HOST}:${PORT}`],
});

const page = await browser.newPage();

// Authenticate before any requests
await page.authenticate({
  username: USER,
  password: PASS,
});

await page.goto("https://ipapi.co/json/");

const response = await page.evaluate(() => document.body.innerText);
console.log(JSON.parse(response));

await browser.close();

This method keeps proxy usage consistent across every page – ideal when you want the same IP identity throughout a session.

Expected result – the API response displays your proxy’s IP address, confirming successful routing.

API response example

Troubleshooting connection failures – If you encounter ERR_TUNNEL_CONNECTION_FAILED or ERR_TIMED_OUT errors:

  • Verify that your proxy credentials haven’t expired

  • Test connectivity using the HypeProxies checker tool

  • Try a different proxy from your pool

Method 2 – context-based proxy isolation

For advanced proxy management, browser contexts let you isolate different sessions inside a single browser instance.

import puppeteer from 'puppeteer';

const RAW = 'YOUR_IP:YOUR_PORT:YOUR_USERNAME:YOUR_PASSWORD';
const [HOST, PORT, USER, PASS] = RAW.split(':');

const proxyUrl = `http://${HOST}:${PORT}`;

const browser = await puppeteer.launch();
const context = await browser.createBrowserContext({
  proxyServer: proxyUrl, // applies to all requests from this context
});

const page = await context.newPage();

await page.authenticate({ username: USER, password: PASS });

await page.goto('https://ipapi.co/json/');

const bodyText = await page.evaluate(() => document.body.innerText.trim());
console.log(bodyText);

await context.close(); // closes pages in this context
await browser.close();

Browser contexts provide full isolation – cookies, storage, and sessions remain separate – while sharing the same browser instance. This makes the approach more resource-efficient than launching multiple browsers.

Method 3 – proxy rotation strategies

Real-world scraping often requires rotating between multiple proxies to distribute requests and reduce detection risks.

Round-robin browser rotation

Launch fresh browser instances with different proxies for maximum isolation:

import puppeteer from "puppeteer";

const proxies = [
  "IP1:PORT1:USER:PASS",
  "IP2:PORT2:USER:PASS",
  "IP3:PORT3:USER:PASS",
];

const testUrl = "https://api.ipify.org";

for (let i = 0; i < proxies.length; i++) {
  const [host, port, username, password] = proxies[i].split(":");

  const browser = await puppeteer.launch({
    args: [`--proxy-server=http://${host}:${port}`],
  });

  const page = await browser.newPage();
  await page.authenticate({
    username,
    password,
  });

  await page.goto(testUrl);
  const result = await page.evaluate(() => document.body.innerText.trim());
  console.log(`Proxy ${i + 1}:`, result);
  await browser.close();
}

Here's what you'll see in your console:

Console output

Each line represents a fresh browser launch with a different proxy.

Context-based rotation

Rotate proxies efficiently by using multiple contexts inside a single browser:

import puppeteer from "puppeteer";

const proxies = [
  "IP1:PORT1:USER:PASS",
  "IP2:PORT2:USER:PASS",
  "IP3:PORT3:USER:PASS",
];

const browser = await puppeteer.launch();
const contexts = [];

// Create contexts for each proxy
for (const proxy of proxies) {
  const [host, port] = proxy.split(":");
  const context = await browser.createBrowserContext({
    proxyServer: `http://${host}:${port}`,
  });
  contexts.push({
    context,
    credentials: proxy,
  });
}

// Use contexts with rotation
for (let i = 0; i < contexts.length; i++) {
  const { context, credentials } = contexts[i];
  const [, , username, password] = credentials.split(":");

  const page = await context.newPage();
  await page.authenticate({
    username,
    password,
  });

  await page.goto("https://api.ipify.org");
  const result = await page.evaluate(() => document.body.innerText.trim());
  console.log(`Context ${i + 1}:`, result);

  await context.close();
}

await browser.close();

The output is:

Console output

This method balances performance and isolation – making it practical for high-volume scraping operations.

Optional – using proxy-chain

The proxy-chain library starts a local, no-auth proxy that forwards to your authenticated upstream. Puppeteer points to the local proxy, so you don’t need page.authenticate() – credentials are handled by proxy-chain.

import puppeteer from "puppeteer";
import proxyChain from "proxy-chain";

const upstreamProxy = "http://USER:PASS@HOST:PORT";

// Start a temporary local, no-auth proxy (e.g., http://127.0.0.1:8000)
const anonymizedProxy = await proxyChain.anonymizeProxy({
  url: upstreamProxy,
});

// Launch Puppeteer via the local proxy
const browser = await puppeteer.launch({
  args: [`--proxy-server=${anonymizedProxy}`],
});

const page = await browser.newPage();
await page.goto("https://ipapi.co/json/");

const result = await page.evaluate(() => document.body.innerText);
console.log(JSON.parse(result));

await browser.close();
// Clean up the local proxy
await proxyChain.closeAnonymizedProxy(anonymizedProxy, true);

See the proxy-chain documentation for additional configuration options and advanced usage patterns.

Best practices

Follow these best practices to keep your proxy-powered scraping stable, efficient, and resilient.

  • Pool management. Rotate proxies to distribute load and reduce rate limits.

  • Error handling. Implement retry logic with fallback proxies.

  • Resource cleanup. Always close browsers and contexts to prevent memory leaks.

  • Monitoring. Log proxy performance to identify and replace failing endpoints.

  • Compliance. Respect target site terms of service and rate limits.

Getting support

Need help with your proxy integration? The HypeProxies team provides support through several channels:

Ready to scale your web scraping with reliable, high-performance proxies? Get started with HypeProxies.

Share on

Stay in the loop

Subscribe to our newsletter for the latest updates, product news, and more.

No spam. Unsubscribe at anytime.

What our clients are saying

What our clients are saying

What our clients are saying

Fast static residential IPs

Proxy plans

Quarterly

10% Off

Monthly

Best value

Starter

Perfect for testing and low-scale usage

$1.40

/ IP

$1.24

/ IP

$35

/month

$31

/month

Quarterly

Cancel at anytime

Pro

Balanced option for daily proxy needs

$1.30

/ IP

$1.16

/ IP

$65

/month

$58

/month

Quarterly

Cancel at anytime

Business

Built for scale and growing demand

$1.25

/ IP

$1.12

/ IP

$125

/month

$112

/month

Quarterly

Cancel at anytime

Enterprise

High-volume power for heavy users

$1.18

/ IP

$1.06

/ IP

$300

/month

$270

/month

Quarterly

Cancel at anytime

Proxies

Bandwidth

Threads

Speed

Support

25 IPs

Unlimited

Unlimited

10GBPS

Standard

50 IPs

Unlimited

Unlimited

10GBPS

Standard

100 IPs

Unlimited

Unlimited

10GBPS

Priority

254 IPs

Subnet

/24 private subnet
on dedicated servers

Unlimited

Unlimited

10GBPS

Dedicated

Crypto

Quarterly

10% Off

Monthly

Starter

Perfect for testing and low-scale usage

$1.40

/ IP

$1.24

/ IP

$35

/month

$31

/month

Quarterly

Cancel at anytime

Get discount below

Proxies

25 IPs

Bandwidth

Unlimited

Threads

Unlimited

Speed

10GBPS

Support

Standard

Pro

Balanced option for daily proxy needs

$1.30

/ IP

$1.16

/ IP

$65

/month

$58

/month

Quarterly

Cancel at anytime

Get discount below

Proxies

50 IPs

Bandwidth

Unlimited

Threads

Unlimited

Speed

10GBPS

Support

Standard

Popular

Business

Built for scale and growing demand

$1.25

/ IP

$1.12

/ IP

$125

/month

$112

/month

Quarterly

Cancel at anytime

Get discount below

Proxies

100 IPs

Bandwidth

Unlimited

Threads

Unlimited

Speed

10GBPS

Support

Priority

Enterprise

High-volume power for heavy users

$1.18

/ IP

$1.06

/ IP

$300

/month

$270

/month

Quarterly

Cancel at anytime

Get discount below

Proxies

254 IPs

Subnet

/24 private subnet
on dedicated servers

Bandwidth

Unlimited

Threads

Unlimited

Speed

10GBPS

Support

Dedicated

Crypto

Quarterly

10% Off

Monthly

Starter

Perfect for testing and low-scale usage

$1.40

/ IP

$1.24

/ IP

$35

/month

$31

/month

Quarterly

Cancel at anytime

Get discount below

Proxies

25 IPs

Bandwidth

Unlimited

Threads

Unlimited

Speed

10GBPS

Support

Standard

Pro

Balanced option for daily proxy needs

$1.30

/ IP

$1.16

/ IP

$65

/month

$58

/month

Quarterly

Cancel at anytime

Get discount below

Proxies

50 IPs

Bandwidth

Unlimited

Threads

Unlimited

Speed

10GBPS

Support

Standard

Popular

Business

Built for scale and growing demand

$1.25

/ IP

$1.12

/ IP

$125

/month

$112

/month

Quarterly

Cancel at anytime

Get discount below

Proxies

100 IPs

Bandwidth

Unlimited

Threads

Unlimited

Speed

10GBPS

Support

Priority

Enterprise

High-volume power for heavy users

$1.18

/ IP

$1.06

/ IP

$300

/month

$270

/month

Quarterly

Cancel at anytime

Get discount below

Proxies

254 IPs

Subnet

/24 private subnet
on dedicated servers

Bandwidth

Unlimited

Threads

Unlimited

Speed

10GBPS

Support

Dedicated

Crypto