What is Puppeteer?
Puppeteer is a Node.js library that drives Chrome and Chromium through the Chrome DevTools Protocol. From JavaScript it launches a browser, opens pages, clicks and types, intercepts network traffic and renders screenshots or PDFs. Teams run it to scrape pages that only assemble their content after JavaScript executes, and to automate logged-in workflows.
The library talks to the browser over a WebSocket using the Chrome DevTools Protocol, the same channel DevTools itself speaks. Installing the npm package pulls down a pinned Chrome for Testing build, so the version you automate is fixed rather than whatever happens to be on the machine. The whole API is asynchronous: puppeteer.launch() hands back a browser and browser.newPage() a tab, and every navigation or query resolves through a promise. Headless is the default; passing headless: false opens a visible window, which is how most people debug a selector that quietly stopped matching. Recent versions can also drive Firefox through WebDriver BiDi.
Proxy configuration happens at launch. You pass --proxy-server=http://host:port, or a socks5:// URL, in the args array, and Chrome routes the entire browser through it. Chrome ignores credentials embedded in that URL, so an authenticated proxy needs page.authenticate({ username, password }), which answers the 407 Proxy Authentication Required challenge for you. Call it before the first navigation, on every page. Newer Puppeteer releases attach a proxy to an individual browser context instead of the whole browser, which is the tidiest way to run several identities inside one process.
Automation leaves marks. Chrome sets navigator.webdriver to true when it runs under the automation flag, and the default headless build reports a user agent that names itself. Permission states, plugin lists and WebGL strings drift from what a real profile reports. The puppeteer-extra-plugin-stealth package patches the loudest of those signals, and it does nothing about your TLS fingerprint or your exit IP. Commercial bot detection correlates all of them together, so a clean mobile or residential address usually changes more outcomes than any single browser patch.
Scale is where Puppeteer gets expensive. Each browser instance holds real memory, and a few dozen concurrent pages will exhaust a small VM. A crashed Chromium can leave a zombie process nobody reaps. Reuse contexts rather than relaunching, and close pages when you are finished with them. Blocking images and fonts through request interception cuts memory and bandwidth when you only need HTML. Inside containers you generally need --no-sandbox or a configured seccomp profile, plus --disable-dev-shm-usage, which stops Chrome dying against Docker's default 64MB /dev/shm.
Where you meet it
You meet Puppeteer the moment an HTTP-only scraper starts returning an empty shell instead of the data you saw in the browser, because the page renders client-side. The follow-up questions arrive quickly: which flag sets the proxy, and why the site loads by hand but returns 403 under automation. Sizing comes after that, since each browser costs memory. Puppeteer is also the standard answer for screenshots, PDF generation and testing a checkout flow that only exists after login.
Common questions
How do I use a proxy with username and password in Puppeteer?
Pass the proxy host and port in the launch args as --proxy-server=http://host:port, then call page.authenticate({ username, password }) on each page before its first navigation. Chrome ignores credentials written into the --proxy-server URL. IP authentication avoids the problem entirely, since no credential exchange happens at all.
Should I use Puppeteer or Playwright?
Playwright drives Chromium, Firefox and WebKit through one API, sets a proxy per browser context, handles proxy credentials natively and waits for elements automatically. Puppeteer is thinner and tracks Chrome closely. New projects usually start with Playwright; an existing Chrome-only Puppeteer suite rarely justifies a rewrite.
Can websites tell that a page is being controlled by Puppeteer?
Often, yes. The automation flag exposes navigator.webdriver, and headless builds differ from a normal profile in fonts, codecs and permission states. Browser-level patches leave the TLS handshake unchanged. Stealth plugins remove some signals, while detection engines score the browser fingerprint alongside behaviour and IP reputation.
Related terms
Real 4G/5G mobile and residential IPs
PROXIES.SX runs carrier IPs in 100+ countries with HTTP and SOCKS5 on every endpoint. $4/GB down to $2.40/GB at volume, free endpoints and rotation, and your GB never expire.