How to Use Proxies with Puppeteer: Complete Guide

TL;DR

Set up GProxy proxies with Puppeteer for headless Chrome automation. Covers proxy authentication, page-level proxy switching, and stealth techniques.

Get Proxies → Puppeteer website →

Language: JavaScript

Prerequisites

✓[
✓"
✓N
✓o
✓d
✓e
✓.
✓j
✓s
✓
✓1
✓6
✓+
✓
✓i
✓n
✓s
✓t
✓a
✓l
✓l
✓e
✓d
✓"
✓,
✓
✓"
✓P
✓u
✓p
✓p
✓e
✓t
✓e
✓e
✓r
✓
✓i
✓n
✓s
✓t
✓a
✓l
✓l
✓e
✓d
✓
✓(
✓n
✓p
✓m
✓
✓i
✓n
✓s
✓t
✓a
✓l
✓l
✓
✓p
✓u
✓p
✓p
✓e
✓t
✓e
✓e
✓r
✓)
✓"
✓,
✓
✓"
✓G
✓P
✓r
✓o
✓x
✓y
✓
✓a
✓c
✓c
✓o
✓u
✓n
✓t
✓
✓w
✓i
✓t
✓h
✓
✓a
✓c
✓t
✓i
✓v
✓e
✓
✓p
✓r
✓o
✓x
✓y
✓
✓p
✓l
✓a
✓n
✓"
✓,
✓
✓"
✓B
✓a
✓s
✓i
✓c
✓
✓J
✓a
✓v
✓a
✓S
✓c
✓r
✓i
✓p
✓t
✓/
✓a
✓s
✓y
✓n
✓c
✓-
✓a
✓w
✓a
✓i
✓t
✓
✓k
✓n
✓o
✓w
✓l
✓e
✓d
✓g
✓e
✓"
✓]

Step-by-Step Setup

[

{

"

T

I

T

L

E

"

:

"

I

N

S

T

A

L

P

U

P

E

T

E

R

"

,

"

D

E

S

C

R

I

P

T

I

O

N

"

:

"

I

N

S

T

A

L

P

U

P

E

T

E

R

W

I

T

H

N

P

M

"

,

"

C

O

D

E

"

:

"

N

P

M

I

N

S

T

A

L

P

100

U

101

P

102

P

103

E

104

T

105

E

106

E

107

R

108

109

P

110

U

111

P

112

P

113

E

114

T

115

E

116

E

117

R

118

-

119

E

120

X

121

T

122

R

123

A

124

125

P

126

U

127

P

128

P

129

E

130

T

131

E

132

E

133

R

134

-

135

E

136

X

137

T

138

R

139

A

140

-

141

P

142

L

143

U

144

G

145

I

146

N

147

-

148

S

149

T

150

E

151

A

152

L

153

T

154

H

155

"

156

}

157

,

158

159

{

160

"

161

T

162

I

163

T

164

L

165

E

166

"

167

:

168

169

"

170

L

171

A

172

U

173

N

174

C

175

H

176

177

B

178

R

179

O

180

W

181

S

182

E

183

R

184

185

W

186

I

187

T

188

H

189

190

P

191

R

192

O

193

X

194

Y

195

"

196

,

197

198

"

199

D

200

E

201

S

202

C

203

R

204

I

205

P

206

T

207

I

208

O

209

N

210

"

211

:

212

213

"

214

C

215

O

216

N

217

F

218

I

219

G

220

U

221

R

222

E

223

224

C

225

H

226

R

227

O

228

M

229

E

230

231

W

232

I

233

T

234

H

235

236

G

237

P

238

R

239

O

240

X

241

Y

242

243

P

244

R

245

O

246

X

247

Y

248

"

249

,

250

251

"

252

C

253

O

254

D

255

E

256

"

257

:

258

259

"

260

C

261

O

262

N

263

S

264

T

265

266

P

267

U

268

P

269

P

270

E

271

T

272

E

273

E

274

R

275

276

=

277

278

R

279

E

280

Q

281

U

282

I

283

R

284

E

285

(

286

'

287

P

288

U

289

P

290

P

291

E

292

T

293

E

294

E

295

R

296

'

297

)

298

;

299

\

300

N

301

\

302

N

303

C

304

O

305

N

306

S

307

T

308

309

B

310

R

311

O

312

W

313

S

314

E

315

R

316

317

=

318

319

A

320

W

321

A

322

I

323

T

324

325

P

326

U

327

P

328

P

329

E

330

T

331

E

332

E

333

R

334

.

335

L

336

A

337

U

338

N

339

C

340

H

341

(

342

{

343

\

344

N

345

346

347

A

348

R

349

G

350

S

351

:

352

353

[

354

'

355

-

356

-

357

P

358

R

359

O

360

X

361

Y

362

-

363

S

364

E

365

R

366

V

367

E

368

R

369

=

370

H

371

T

372

T

373

P

374

:

375

/

376

/

377

P

378

R

379

O

380

X

381

Y

382

.

383

G

384

P

385

R

386

O

387

X

388

Y

389

.

390

N

391

E

392

T

393

:

394

1

395

0

396

0

397

0

398

'

399

]

400

\

401

N

402

}

403

)

404

;

405

\

406

N

407

C

408

O

409

N

410

S

411

T

412

413

P

414

A

415

G

416

E

417

418

=

419

420

A

421

W

422

A

423

I

424

T

425

426

B

427

R

428

O

429

W

430

S

431

E

432

R

433

.

434

N

435

E

436

W

437

P

438

A

439

G

440

E

441

(

442

)

443

;

444

"

445

}

446

,

447

448

{

449

"

450

T

451

I

452

T

453

L

454

E

455

"

456

:

457

458

"

459

A

460

U

461

T

462

H

463

E

464

N

465

T

466

I

467

C

468

A

469

T

470

E

471

472

W

473

I

474

T

475

H

476

477

P

478

R

479

O

480

X

481

Y

482

"

483

,

484

485

"

486

D

487

E

488

S

489

C

490

R

491

I

492

P

493

T

494

I

495

O

496

N

497

"

498

:

499

500

"

501

S

502

E

503

T

504

505

P

506

R

507

O

508

X

509

Y

510

511

C

512

R

513

E

514

D

515

E

516

N

517

T

518

I

519

A

520

L

521

S

522

523

U

524

S

525

I

526

N

527

G

528

529

P

530

A

531

G

532

E

533

.

534

A

535

U

536

T

537

H

538

E

539

N

540

T

541

I

542

C

543

A

544

T

545

E

546

(

547

)

548

"

549

,

550

551

"

552

C

553

O

554

D

555

E

556

"

557

:

558

559

"

560

A

561

W

562

A

563

I

564

T

565

566

P

567

A

568

G

569

E

570

.

571

A

572

U

573

T

574

H

575

E

576

N

577

T

578

I

579

C

580

A

581

T

582

E

583

(

584

{

585

\

586

N

587

588

589

U

590

S

591

E

592

R

593

N

594

A

595

M

596

E

597

:

598

599

'

600

Y

601

O

602

U

603

R

604

_

605

U

606

S

607

E

608

R

609

N

610

A

611

M

612

E

613

'

614

,

615

\

616

N

617

618

619

P

620

A

621

S

622

S

623

W

624

O

625

R

626

D

627

:

628

629

'

630

Y

631

O

632

U

633

R

634

_

635

P

636

A

637

S

638

S

639

W

640

O

641

R

642

D

643

'

644

\

645

N

646

}

647

)

648

;

649

\

650

N

651

\

652

N

653

A

654

W

655

A

656

I

657

T

658

659

P

660

A

661

G

662

E

663

.

664

G

665

O

666

T

667

O

668

(

669

'

670

H

671

T

672

T

673

P

674

S

675

:

676

/

677

/

678

H

679

T

680

T

681

P

682

B

683

I

684

N

685

.

686

O

687

R

688

G

689

/

690

I

691

P

692

'

693

)

694

;

695

\

696

N

697

C

698

O

699

N

700

S

701

O

702

L

703

E

704

.

705

L

706

O

707

G

708

(

709

A

710

W

711

A

712

I

713

T

714

715

P

716

A

717

G

718

E

719

.

720

C

721

O

722

N

723

T

724

E

725

N

726

T

727

(

728

)

729

)

730

;

731

"

732

}

733

,

734

735

{

736

"

737

T

738

I

739

T

740

L

741

E

742

"

743

:

744

745

"

746

A

747

D

748

D

749

750

S

751

T

752

E

753

A

754

L

755

T

756

H

757

758

P

759

L

760

U

761

G

762

I

763

N

764

"

765

,

766

767

"

768

D

769

E

770

S

771

C

772

R

773

I

774

P

775

T

776

I

777

O

778

N

779

"

780

:

781

782

"

783

U

784

S

785

E

786

787

P

788

U

789

P

790

P

791

E

792

T

793

E

794

E

795

R

796

-

797

E

798

X

799

T

800

R

801

A

802

-

803

P

804

L

805

U

806

G

807

I

808

N

809

-

810

S

811

T

812

E

813

A

814

L

815

T

816

H

817

818

T

819

O

820

821

A

822

V

823

O

824

I

825

D

826

827

D

828

E

829

T

830

E

831

C

832

T

833

I

834

O

835

N

836

"

837

,

838

839

"

840

C

841

O

842

D

843

E

844

"

845

:

846

847

"

848

C

849

O

850

N

851

S

852

T

853

854

P

855

U

856

P

857

P

858

E

859

T

860

E

861

E

862

R

863

864

=

865

866

R

867

E

868

Q

869

U

870

I

871

R

872

E

873

(

874

'

875

P

876

U

877

P

878

P

879

E

880

T

881

E

882

E

883

R

884

-

885

E

886

X

887

T

888

R

889

A

890

'

891

)

892

;

893

\

894

N

895

C

896

O

897

N

898

S

899

T

900

901

S

902

T

903

E

904

A

905

L

906

T

907

H

908

P

909

L

910

U

911

G

912

I

913

N

914

915

=

916

917

R

918

E

919

Q

920

U

921

I

922

R

923

E

924

(

925

'

926

P

927

U

928

P

929

P

930

E

931

T

932

E

933

E

934

R

935

-

936

E

937

X

938

T

939

R

940

A

941

-

942

P

943

L

944

U

945

G

946

I

947

N

948

-

949

S

950

T

951

E

952

A

953

L

954

T

955

H

956

'

957

)

958

;

959

\

960

N

961

P

962

U

963

P

964

P

965

E

966

T

967

E

968

E

969

R

970

.

971

U

972

S

973

E

974

(

975

S

976

T

977

E

978

A

979

L

980

T

981

H

982

P

983

L

984

U

985

G

986

I

987

N

988

(

989

)

990

)

991

;

992

\

993

N

994

\

995

N

996

C

997

O

998

N

999

S

1000

T

1001

1002

B

1003

R

1004

O

1005

W

1006

S

1007

E

1008

R

1009

1010

=

1011

1012

A

1013

W

1014

A

1015

I

1016

T

1017

1018

P

1019

U

1020

P

1021

P

1022

E

1023

T

1024

E

1025

E

1026

R

1027

.

1028

L

1029

A

1030

U

1031

N

1032

C

1033

H

1034

(

1035

{

1036

\

1037

N

1038

1039

1040

A

1041

R

1042

G

1043

S

1044

:

1045

1046

[

1047

'

1048

-

1049

-

1050

P

1051

R

1052

O

1053

X

1054

Y

1055

-

1056

S

1057

E

1058

R

1059

V

1060

E

1061

R

1062

=

1063

H

1064

T

1065

T

1066

P

1067

:

1068

/

1069

/

1070

P

1071

R

1072

O

1073

X

1074

Y

1075

.

1076

G

1077

P

1078

R

1079

O

1080

X

1081

Y

1082

.

1083

N

1084

E

1085

T

1086

:

1087

1

1088

0

1089

0

1090

0

1091

'

1092

]

1093

\

1094

N

1095

}

1096

)

1097

;

1098

"

1099

}

1100

,

1101

1102

{

1103

"

1104

T

1105

I

1106

T

1107

L

1108

E

1109

"

1110

:

1111

1112

"

1113

B

1114

L

1115

O

1116

C

1117

K

1118

1119

U

1120

N

1121

N

1122

E

1123

C

1124

E

1125

S

1126

S

1127

A

1128

R

1129

Y

1130

1131

R

1132

E

1133

S

1134

O

1135

U

1136

R

1137

C

1138

E

1139

S

1140

"

1141

,

1142

1143

"

1144

D

1145

E

1146

S

1147

C

1148

R

1149

I

1150

P

1151

T

1152

I

1153

O

1154

N

1155

"

1156

:

1157

1158

"

1159

S

1160

P

1161

E

1162

E

1163

D

1164

1165

U

1166

P

1167

1168

S

1169

C

1170

R

1171

A

1172

P

1173

I

1174

N

1175

G

1176

1177

B

1178

Y

1179

1180

B

1181

L

1182

O

1183

C

1184

K

1185

I

1186

N

1187

G

1188

1189

I

1190

M

1191

A

1192

G

1193

E

1194

S

1195

1196

A

1197

N

1198

D

1199

1200

F

1201

O

1202

N

1203

T

1204

S

1205

"

1206

,

1207

1208

"

1209

C

1210

O

1211

D

1212

E

1213

"

1214

:

1215

1216

"

1217

A

1218

W

1219

A

1220

I

1221

T

1222

1223

P

1224

A

1225

G

1226

E

1227

.

1228

S

1229

E

1230

T

1231

R

1232

E

1233

Q

1234

U

1235

E

1236

S

1237

T

1238

I

1239

N

1240

T

1241

E

1242

R

1243

C

1244

E

1245

P

1246

T

1247

I

1248

O

1249

N

1250

(

1251

T

1252

R

1253

U

1254

E

1255

)

1256

;

1257

\

1258

N

1259

P

1260

A

1261

G

1262

E

1263

.

1264

O

1265

N

1266

(

1267

'

1268

R

1269

E

1270

Q

1271

U

1272

E

1273

S

1274

T

1275

'

1276

,

1277

1278

(

1279

R

1280

E

1281

Q

1282

)

1283

1284

=

1285

>

1286

1287

{

1288

\

1289

N

1290

1291

1292

I

1293

F

1294

1295

(

1296

[

1297

'

1298

I

1299

M

1300

A

1301

G

1302

E

1303

'

1304

,

1305

1306

'

1307

F

1308

O

1309

N

1310

T

1311

'

1312

,

1313

1314

'

1315

S

1316

T

1317

Y

1318

L

1319

E

1320

S

1321

H

1322

E

1323

E

1324

T

1325

'

1326

]

1327

.

1328

I

1329

N

1330

C

1331

L

1332

U

1333

D

1334

E

1335

S

1336

(

1337

R

1338

E

1339

Q

1340

.

1341

R

1342

E

1343

S

1344

O

1345

U

1346

R

1347

C

1348

E

1349

T

1350

Y

1351

P

1352

E

1353

(

1354

)

1355

)

1356

)

1357

\

1358

N

1359

1360

1361

1362

1363

R

1364

E

1365

Q

1366

.

1367

A

1368

B

1369

O

1370

R

1371

T

1372

(

1373

)

1374

;

1375

\

1376

N

1377

1378

1379

E

1380

L

1381

S

1382

E

1383

\

1384

N

1385

1386

1387

1388

1389

R

1390

E

1391

Q

1392

.

1393

C

1394

O

1395

N

1396

T

1397

I

1398

N

1399

U

1400

E

1401

(

1402

)

1403

;

1404

\

1405

N

1406

}

1407

)

1408

;

1409

"

1410

}

1411

,

1412

1413

{

1414

"

1415

T

1416

I

1417

T

1418

L

1419

E

1420

"

1421

:

1422

1423

"

1424

T

1425

E

1426

S

1427

T

1428

1429

A

1430

N

1431

D

1432

1433

V

1434

E

1435

R

1436

I

1437

F

1438

Y

1439

"

1440

,

1441

1442

"

1443

D

1444

E

1445

S

1446

C

1447

R

1448

I

1449

P

1450

T

1451

I

1452

O

1453

N

1454

"

1455

:

1456

1457

"

1458

C

1459

O

1460

N

1461

F

1462

I

1463

R

1464

M

1465

1466

T

1467

H

1468

E

1469

1470

P

1471

R

1472

O

1473

X

1474

Y

1475

1476

I

1477

S

1478

1479

W

1480

O

1481

R

1482

K

1483

I

1484

N

1485

G

1486

1487

C

1488

O

1489

R

1490

R

1491

E

1492

C

1493

T

1494

L

1495

Y

1496

"

1497

,

1498

1499

"

1500

C

1501

O

1502

D

1503

E

1504

"

1505

:

1506

1507

"

1508

A

1509

W

1510

A

1511

I

1512

T

1513

1514

P

1515

A

1516

G

1517

E

1518

.

1519

G

1520

O

1521

T

1522

O

1523

(

1524

'

1525

H

1526

T

1527

T

1528

P

1529

S

1530

:

1531

/

1532

/

1533

H

1534

T

1535

T

1536

P

1537

B

1538

I

1539

N

1540

.

1541

O

1542

R

1543

G

1544

/

1545

I

1546

P

1547

'

1548

)

1549

;

1550

\

1551

N

1552

C

1553

O

1554

N

1555

S

1556

T

1557

1558

B

1559

O

1560

D

1561

Y

1562

1563

=

1564

1565

A

1566

W

1567

A

1568

I

1569

T

1570

1571

P

1572

A

1573

G

1574

E

1575

.

1576

E

1577

V

1578

A

1579

L

1580

U

1581

A

1582

T

1583

E

1584

(

1585

(

1586

)

1587

1588

=

1589

>

1590

1591

D

1592

O

1593

C

1594

U

1595

M

1596

E

1597

N

1598

T

1599

.

1600

B

1601

O

1602

D

1603

Y

1604

.

1605

I

1606

N

1607

N

1608

E

1609

R

1610

T

1611

E

1612

X

1613

T

1614

)

1615

;

1616

\

1617

N

1618

C

1619

O

1620

N

1621

S

1622

O

1623

L

1624

E

1625

.

1626

L

1627

O

1628

G

1629

(

1630

'

1631

C

1632

U

1633

R

1634

R

1635

E

1636

N

1637

T

1638

1639

I

1640

P

1641

:

1642

'

1643

,

1644

1645

J

1646

S

1647

O

1648

N

1649

.

1650

P

1651

A

1652

R

1653

S

1654

E

1655

(

1656

B

1657

O

1658

D

1659

Y

1660

)

1661

.

1662

O

1663

R

1664

I

1665

G

1666

I

1667

N

1668

)

1669

;

1670

\

1671

N

1672

A

1673

W

1674

A

1675

I

1676

T

1677

1678

B

1679

R

1680

O

1681

W

1682

S

1683

E

1684

R

1685

.

1686

C

1687

L

1688

O

1689

S

1690

E

1691

(

1692

)

1693

;

1694

"

1695

}

1696

]

Code Examples

Why Use Proxies with Puppeteer?

Puppeteer is Google's official Node.js library for controlling headless Chrome. It's widely used for web scraping, testing, and automation. When accessing websites at scale, you need proxies to avoid IP blocks and rate limits. GProxy's pool of 10M+ residential IPs across 150+ countries makes your Puppeteer scripts appear as real users from any location.

Basic Proxy Setup

Puppeteer supports proxy configuration through Chrome launch arguments. Pass --proxy-server when launching the browser. For GProxy's HTTP proxies, the format is straightforward. Unlike Selenium, Puppeteer gives you programmatic control over proxy authentication through the page.authenticate() method, eliminating the need for browser extensions.

Per-Page Proxy Authentication

Puppeteer's page.authenticate() method handles proxy authentication elegantly. Call it before navigating to set credentials that will be sent automatically when the proxy requests authentication. This works with GProxy's username/password authentication out of the box.

Proxy Rotation Strategies

With Puppeteer, you have two rotation strategies: browser-level (launch a new browser per proxy) and context-level (create new incognito contexts). Browser contexts are lighter than full browser instances and support different proxy configurations per context, making them ideal for concurrent scraping with different IPs.

Stealth and Anti-Detection

Modern websites use fingerprinting to detect automated browsers. Combine GProxy residential proxies with puppeteer-extra and the stealth plugin to evade detection. The stealth plugin patches common detection vectors like navigator.webdriver, chrome.runtime, and WebGL fingerprints.

Performance Optimization

Optimize Puppeteer with proxies by: blocking unnecessary resources (images, fonts, CSS) using request interception, setting appropriate timeouts, reusing browser instances with fresh pages, and using GProxy's datacenter proxies for speed-critical non-sensitive scraping tasks.

Use Cases

[

{

"

T

I

T

L

E

"

:

"

S

P

A

S

C

R

A

P

I

N

G

"

,

"

D

E

S

C

R

I

P

T

I

O

N

"

:

"

S

C

R

A

P

E

S

I

N

G

L

E

-

P

A

G

E

A

P

L

I

C

A

T

I

O

N

S

T

H

A

T

R

E

Q

U

I

R

E

J

A

V

A

S

C

R

I

P

T

E

X

E

C

U

T

I

O

N

T

O

R

E

N

D

E

R

C

O

N

T

E

N

T

.

"

}

,

{

"

T

I

T

L

E

"

:

"

S

C

R

E

N

S

H

O

T

S

E

R

V

I

C

E

S

"

,

"

D

E

S

C

R

I

P

T

I

O

N

"

:

"

G

E

N

E

R

A

T

E

W

E

B

S

I

T

E

S

C

R

E

N

S

H

O

T

S

F

R

O

M

D

I

F

E

R

E

N

T

C

O

U

N

T

R

I

E

S

U

S

I

N

G

E

O

-

T

A

R

G

E

T

E

D

P

R

O

X

I

E

S

.

"

}

,

{

"

T

I

T

L

E

"

:

"

P

R

I

C

E

C

O

M

P

A

R

I

S

O

N

"

,

"

D

E

S

C

R

I

P

T

I

O

N

"

:

"

M

O

N

I

T

O

R

C

O

M

P

E

T

I

T

O

R

P

R

I

C

E

S

A

C

R

O

S

R

E

G

I

O

N

S

W

I

T

H

L

O

C

A

T

I

O

N

-

S

P

E

C

I

F

I

C

R

E

S

I

D

E

N

T

I

A

L

I

P

S

.

"

}

,

{

"

T

I

T

L

E

"

:

"

S

O

C

I

A

L

M

E

D

I

A

U

T

O

M

A

T

I

O

N

"

,

"

D

E

S

C

R

I

P

T

I

O

N

"

:

"

A

U

T

O

M

A

T

E

S

O

C

I

A

L

M

E

D

I

A

W

O

R

K

F

L

O

W

S

W

I

T

H

U

N

I

Q

U

E

I

P

S

P

E

R

A

C

O

U

N

T

.

"

}

]

Pro Tips

Use browser contexts instead of new browser instances for faster proxy rotation. Block images and fonts via request interception to save bandwidth. Set viewport to 1920x1080 to avoid mobile detection. Combine stealth plugin with GProxy residential IPs for maximum evasion.