> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/integrations/proxy-integrations/puppeteer.md).

# Puppeteer

[**Puppeteer**](https://developer.chrome.com/docs/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**](#residential-and-mobile-proxies)
* [**Datacenter Proxies**](#datacenter-proxies)
* [**Dedicated Datacenter Proxies (Enterprise)**](#dedicated-datacenter-proxies-enterprise)
* [**Dedicated Datacenter Proxies (Self-service)**](#dedicated-datacenter-proxies-self-service)
* [**ISP Proxies**](#isp-proxies)
* [**Dedicated ISP Proxies**](#dedicated-isp-proxies)

{% embed url="<https://youtu.be/9xyvfs0Qikw>" %}

### **Step 1**

Install [Node.js](https://nodejs.org/en/download) 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.&#x20;

### **Step 3**

Within Puppeteer, fill in the value, for example:

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

```javascript
(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](#residential-and-mobile-proxies)
* [Datacenter Proxies](#datacenter-proxies)
* [Dedicated Datacenter Proxies (Enterprise)](#dedicated-datacenter-proxies-enterprise)
* [Dedicated Datacenter Proxies (Self-service)](#dedicated-datacenter-proxies-self-service)
* [ISP Proxies](#isp-proxies)
* [Dedicated ISP Proxies](#dedicated-isp-proxies)

#### Residential & Mobile Proxies

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

**Host:** `pr.oxylabs.io`

**Port:** `7777`

**Username:** `customer-USERNAME`

**Password:** `PASSWORD`

{% hint style="warning" %}
**Note:** Don't forget to add `customer-` prefix to your username.
{% endhint %}

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](/products/proxies/residential-proxies.md) to learn more.

#### Datacenter Proxies

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

**Host:** `dc.oxylabs.io`

**Port:** `8001`

**Username:** `user-username`

**Password:** `password`

{% hint style="warning" %}
**Note:** Don't forget to add `user-` prefix to your username.
{% endhint %}

**Pay-per-IP subscription**

The port is the sequential number assigned to an IP address from the [proxy list](/products/proxies/datacenter-proxies/proxy-list.md). Thus, port `8001` uses the first IP address from your list. You may also enable [proxy IP rotation](/products/proxies/datacenter-proxies/ip-control.md) by setting the port to `8000`.

Furthermore, you can specify the [geo-location](/products/proxies/datacenter-proxies/select-country.md), 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](/products/proxies/datacenter-proxies/ip-control.md) with each request by using port `8000`.

If you want to use a specific [geo-location](/products/proxies/datacenter-proxies/select-country.md), for example, the US, set the Proxy username to `user-USERNAME-country-US`.

#### Dedicated Datacenter Proxies (Enterprise)

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

**Host:** `1.2.3.4` (IP address from your [proxy list](/products/proxies/dedicated-datacenter-proxies/enterprise/proxy-lists.md))

**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](/products/proxies/dedicated-datacenter-proxies/enterprise/proxy-lists.md).

#### Dedicated Datacenter Proxies (Self-service)

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

**Host:** `ddc.oxylabs.io`

**Port:** `8001`

**Username:** `user-username`

**Password:** `password`

{% hint style="warning" %}
**Note:** Don't forget to add `user-` prefix to your username.
{% endhint %}

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](/products/proxies/dedicated-datacenter-proxies/self-service/proxy-list.md). If you want to get a different IP with each request, change the Port to `8000` to enable [proxy rotation](/products/proxies/dedicated-datacenter-proxies/self-service/proxy-rotation.md).

#### ISP Proxies

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

**Host:** `isp.oxylabs.io`

**Port:** `8001`

**Username:** `user-username`

**Password:** `password`

{% hint style="warning" %}
**Note:** Don't forget to add `user-` prefix to your username.
{% endhint %}

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](/products/proxies/isp-proxies/proxy-list.md). If you want to get a different IP with each request, change the Port to `8000` to enable [proxy rotation](/products/proxies/isp-proxies/proxy-rotation.md).

#### Dedicated ISP Proxies

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

**Host:** `disp.oxylabs.io`

**Port:** `8001`

**Username:** `user-username`

**Password:** `password`

{% hint style="warning" %}
**Note:** Don't forget to add `user-` prefix to your username.
{% endhint %}

You will need to choose the port assigned to an IP address from the purchased [proxy list](/products/proxies/dedicated-isp-proxies/self-service/proxy-list.md), 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](/products/proxies/dedicated-isp-proxies/self-service/proxy-rotation.md).

### **Step 4**

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

```javascript
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();
})();
```

{% hint style="warning" %}
**Note:** Don't forget to add `customer-` or  `user-` prefix to your username if the chosen proxy type requires it.
{% endhint %}

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](https://oxylabs.io/resources/integrations/puppeteer).

If you want to learn more about web scraping with Puppeteer, read our [blog post](https://oxylabs.io/blog/puppeteer-tutorial).

### Common errors

<details>

<summary><strong>Puppeteer is returning an error</strong></summary>

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.&#x20;

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.

</details>

<details>

<summary><strong>The page isn't loading</strong></summary>

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.&#x20;

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.

</details>

<details>

<summary><strong>Other issues</strong></summary>

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.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/integrations/proxy-integrations/puppeteer.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.