Puppeteer

Set up Puppeteer with Oxylabs Proxies to control headless Chrome or Chromium via Node.js. Step-by-step guide with code examples.

Puppeteer is a Node library that provides a high-level API to control headless Chrome or Chromium over the DevTools Protocol.

Watch our video guide or follow the steps below to integrate Puppeteer with the following Oxylabs proxies:

• Residential & Mobile Proxies
• Datacenter Proxies
• Dedicated Datacenter Proxies (Enterprise)
• Dedicated Datacenter Proxies (Self-service)
• ISP Proxies
• Dedicated ISP Proxies

Step 1

Install Node.js and a code editor of your choice. (Skip this step If you already have it)

Step 2

Create a Node.js project and install the required packages.

Step 3

Within Puppeteer, fill in the value, for example:

Within your Puppeteer script, assign the --proxy-server value as shown below:

(async () => {
    const browser = await puppeteer.launch({
        headless: false,
        args: [`--proxy-server=host:port`]
    });

Enter your server value according to your chosen Oxylabs proxy type:

• Residential & Mobile Proxies
• Datacenter Proxies
• Dedicated Datacenter Proxies (Enterprise)
• Dedicated Datacenter Proxies (Self-service)
• ISP Proxies
• Dedicated ISP Proxies

Residential & Mobile Proxies

args: [`--proxy-server=pr.oxylabs.io:7777`] //--proxy-server=host:port

Host: pr.oxylabs.io

Port: 7777

Username: customer-USERNAME

Password: PASSWORD

Note: Don't forget to add customer- prefix to your username.

You may also use additional parameters with residential and mobile proxies to set the geo-location (country, state, city, and etc.) and control sessions. Check out the Residential Proxies documentation to learn more.

Datacenter Proxies

args: [`--proxy-server=dc.oxylabs.io:8001`] //--proxy-server=host:port

Host: dc.oxylabs.io

Port: 8001

Username: user-username

Password: password

Note: Don't forget to add user- prefix to your username.

Pay-per-IP subscription

The port is the sequential number assigned to an IP address from the proxy list. Thus, port 8001 uses the first IP address from your list. You may also enable proxy IP rotation by setting the port to 8000.

Furthermore, you can specify the geo-location, for example, the US, by setting the Proxy username to user-USERNAME-country-US.

Pay-per-traffic subscription

The port 8001 picks a random IP address but stays consistent during a session. Alternatively, you can rotate proxy IPs with each request by using port 8000.

If you want to use a specific geo-location, for example, the US, set the Proxy username to user-USERNAME-country-US.

Dedicated Datacenter Proxies (Enterprise)

args: [`--proxy-server=1.2.3.4:60000`] //--proxy-server=host:port

Host: 1.2.3.4 (IP address from your proxy list)

Port: 60000 (HTTP), 1180 (SOCKS5)

Username: username

Password: password

For Enterprise Dedicated Datacenter Proxies (purchased through sales team), you’ll have to choose an IP address from the acquired proxy list.

Dedicated Datacenter Proxies (Self-service)

args: [`--proxy-server=ddc.oxylabs.io:8001`] //--proxy-server=host:port

Host: ddc.oxylabs.io

Port: 8001

Username: user-username

Password: password

Note: Don't forget to add user- prefix to your username.

For Self-Service Dedicated Datacenter Proxies (purchased through Oxylabs dashboard), the port indicates the sequential number of an IP address from the acquired proxy list. If you want to get a different IP with each request, change the Port to 8000 to enable proxy rotation.

ISP Proxies

args: [`--proxy-server=isp.oxylabs.io:8001`] //--proxy-server=host:port

Host: isp.oxylabs.io

Port: 8001

Username: user-username

Password: password

Note: Don't forget to add user- prefix to your username.

With ISP Proxies, the port is assigned to a specific IP address and its location. Hence, port 8001 will always pick the first IP from your proxy list. If you want to get a different IP with each request, change the Port to 8000 to enable proxy rotation.

Dedicated ISP Proxies

args: [`--proxy-server=disp.oxylabs.io:8001`] //--proxy-server=host:port

Host: disp.oxylabs.io

Port: 8001

Username: user-username

Password: password

Note: Don't forget to add user- prefix to your username.

You will need to choose the port assigned to an IP address from the purchased proxy list, which you can find on the Oxylabs dashboard. The 8001 port will pick the first IP address from your list for all requests. Use port 8000 for automatic proxy IP rotation.

Step 4

Under the page.authenticate(), enter your Oxylabs proxy user's username and password. A basic code example should look something like this:

const puppeteer = require('puppeteer');
(async () => {
  const browser = await puppeteer.launch({
    headless: false,
    args: ['--proxy-server=pr.oxylabs.io:7777]  
});
  const page = await browser.newPage();
    await page.authenticate({
        username: 'USERNAME',
        password: 'PASSWORD'
    });
    await page.goto('https://ip.oxylabs.io');
    await page.screenshot({path: 'example.png'});
    await browser.close();
})();

Note: Don't forget to add customer- or user- prefix to your username if the chosen proxy type requires it.

And that's it! You've successfully integrated Oxylabs proxies with Puppeteer. You can also find the proxy-chain tutorial and the rotating proxy guides in the original Puppeteer integration blog post here.

If you want to learn more about web scraping with Puppeteer, read our blog post.

Common errors

Puppeteer is returning an error

One of the issues you might encounter is having Puppeteer return an error when you’re trying to connect to a proxy server. The reasons for that may be diverse, with the main one being your proxy server requiring authentication with the proxy credentials.

To solve this problem, you'll need to enter the username and password for your proxy server in the Puppeteeroptions object. After that, try using a proxy again.

The page isn't loading

Even though Puppeteer might be able to connect to the proxy, it still may have trouble loading the page. The most common reason for it's a poor internet connection.

The most common method to fix this issue is to increase the timeout in the Puppeteeroptions object. Once done, using a proxy should no longer be a problem.

Other issues

If the issue remains unresolved, it means that, for some reason, your proxy fails to maintain the connection. In this case, you should check your proxy server or contact your provider for further assistance.