How to Set Up Proxies with Puppeteer (Configuration Tutorial)

Puppeteer is a Node.js library that provides a high-level API to control headless Chrome/Chromium. It's commonly used for web scraping, automation, testing and more.

Proxies are very beneficial to use with Puppeteer, as they allow:

  • Rotating IPs to avoid detection
  • Accessing geo-restricted content
  • Adding anonymity to requests

In this comprehensive guide, we'll cover integrating various proxy services with Puppeteer across major operating systems:

  • BrightData – Residential proxies from over 72 million IPs worldwide
  • Smartproxy – US and EU-based datacenter proxy networks
  • Proxy-Seller – Anonymous proxies from a variety of sellers
  • Soax – Targeted residential proxies for sites like Instagram

Configure Proxies with Puppeteer on Windows

Installing Puppeteer on Windows

To use Puppeteer on Windows, we first need to install Node.js and the Puppeteer package:

Install Node.js

  1. Download the latest Node.js installer from
  2. Run the .msi installer and follow the setup wizard prompts
  3. Restart your computer after installation
  4. Verify Node is installed by running node -v in PowerShell or Command Prompt

Install Puppeteer Package

  1. Open PowerShell or Command Prompt as administrator
  2. Run npm install puppeteer to install the Puppeteer package
  3. Test it quickly with node -e "require('puppeteer')" to confirm no errors

Now we have our environment set up to start using Puppeteer on Windows!

Configuring Proxies in Puppeteer on Windows

With Puppeteer installed, we can configure proxies by passing them in the puppeteer.launch() options:

const browser = await puppeteer.launch({
  args: [`--proxy-server=proxy-host:port`] 

Some examples:

BrightData Residential Proxy

args: ['']

Smartproxy Datacenter Proxy

args: ['--proxy-server=']

Soax Instagram Proxy

args: ['']

We can also authenticate proxies that require a username and password:

const page = await browser.newPage();

await page.authenticate({
  username: 'proxy_user',
  password: 'proxy_pass' 

Other configuration tips on Windows:

  • Set proxies at the Chromium level to apply across browsers
  • Use PowerShell environment variables for proxy credentials
  • Ensure Windows firewall allows connections to proxy hosts

With proxies configured, we can now send traffic through them in Puppeteer scripts on Windows!

Troubleshooting Puppeteer Proxies on Windows

Some common issues and fixes:

  • Authentication errors – confirm username & password are correct
  • Connection issues – allow proxy host in firewall rules
  • Browser not using proxy – double check launch options
  • Node.js proxy problems – set HTTP_PROXY env var

Reaching out to your proxy provider's support can also help diagnose Windows-specific problems.

Configure Proxies with Puppeteer on macOS

Installing Puppeteer on macOS

Before using Puppeteer, we need to set up the prerequisites on macOS:

Install Node.js

  1. Download the macOS installer from
  2. Open the .pkg file and follow the installation prompts
  3. Confirm installation with node -v in Terminal

Install Puppeteer Package

  1. Open Terminal and run npm install puppeteer
  2. Test it with node -e "require('puppeteer')" to check for errors
  3. Consider using a node version manager like nvm to manage Node.js versions

Now Puppeteer is ready to use on macOS!

Configuring Proxies in Puppeteer on macOS

We pass proxies to Puppeteer using the --proxy-server launch argument:

const browser = await puppeteer.launch({
  args: [`--proxy-server=proxy-host:port`]

For example:

Smartproxy Datacenter Proxy

args: ['--proxy-server=']

Soax Instagram Proxy

args: ['']

To authenticate:

const page = await browser.newPage();

await page.authenticate({
  username: 'proxyuser',
  password: 'proxypass'

Other macOS proxy tips:

  • Set proxy globally under Network preferences
  • Use Terminal export for proxy credentials
  • Enable proxy connections in macOS firewall

With the above steps, you can leverage proxies for automation using Puppeteer on macOS!

Troubleshooting Puppeteer Proxies on macOS

Some common macOS proxy issues:

  • Browser not routing traffic through proxy – check network settings
  • Authentication failing – confirm valid credentials provided
  • Install certificate for TLS proxy connections
  • Canvas/WebGL rendering problems – disable proxy for these

Work with your proxy provider's support to troubleshoot any macOS-specific proxy problems in Puppeteer.

Configure Proxies with Puppeteer on Linux

Installing Puppeteer on Linux

To use Puppeteer on Linux, you'll need:

Install Node.js

  • sudo apt install nodejs on Debian/Ubuntu
  • sudo yum install nodejs on RHEL/CentOS

Or install from Nodesource

Install Puppeteer Package

npm install puppeteer

Test with node -e "require('puppeteer')"

Consider using nvm to manage Node.js versions.

Configuring Proxies in Puppeteer on Linux

We pass the proxy URL to Puppeteer during launch:

const browser = await puppeteer.launch({
  args: [`--proxy-server=proxy-host:port`] 

For example:

BrightData Residential Proxy

args: ['']

Proxy-Seller Anonymous Proxy

args: ['--proxy-server=']

To authenticate:

const page = await browser.newPage();

await page.authenticate({
  username: 'proxyuser', 
  password: 'proxypass'

Other Linux proxy configuration tips:

  • Export proxy environment variables
  • Add CA certificate for TLS proxy authentication
  • Set proxy globally for all browsers to use

This allows leveraging proxies for web automation using Puppeteer on Linux!

Troubleshooting Puppeteer Proxies on Linux

Some common Linux proxy issues:

  • Browser not routing traffic through proxy – check environment variables
  • Node.js unable to connect to proxy – may need CA certificate
  • Authentication failure – validate credentials provided
  • Connection timeouts – increase timeout thresholds

Work with your proxy provider for Linux-specific troubleshooting and support.

Comparing Proxy Providers

Not all proxy services are created equal. Here are some key metrics to evaluate providers:

  • Uptime – Amount of downtime and reliability of the network
  • Latency – Network speeds from various geographic regions
  • Bandwidth – Maximum throughput and requests per proxy
  • Stickiness – How frequently IPs are rotated for each account
  • Location targeting – Ability to geo-target specific countries and cities

Run your own benchmarking tests to determine the best performing providers for your use case. Mixing multiple vendors helps maximize proxy diversity.

Best Practices for Proxy Usage

Follow these tips for smooth proxy operation:

  • Warm up proxies before fully unleashing – let them build up usage history with sites
  • Mimic human behavior like mouse movements and scrolling when interacting through proxies
  • Use appropriate headers like User-Agent to appear more natural
  • Always respect site terms and access data ethically

Carefully configured responsibly proxies provide a robust foundation for large-scale automation and scraping projects.


This guide details integrating various proxy types with Puppeteer on Windows, macOS, and Linux. Proper proxy usage unlocks powerful capabilities for headless browser automation.

With the configuration tips provided here, you should have a complete understanding of how to leverage proxies effectively in your Puppeteer scripts. Let me know if you have any other questions!

John Rooney

John Rooney

John Watson Rooney, a self-taught Python developer and content creator with a focus on web scraping, APIs, and automation. I love sharing my knowledge and expertise through my YouTube channel, My channel caters to all levels of developers, from beginners looking to get started in web scraping to experienced programmers seeking to advance their skills with modern techniques. I have worked in the e-commerce sector for many years, gaining extensive real-world experience in data handling, API integrations, and project management. I am passionate about teaching others and simplifying complex concepts to make them more accessible to a wider audience. In addition to my YouTube channel, I also maintain a personal website where I share my coding projects and other related content.

We will be happy to hear your thoughts

      Leave a reply

      Compare items
      • Total (0)