Installing and Configuring Puppeteer: Solving Common Dependency and Chromium Issues

Want to automate Chrome or Chromium with ease? Puppeteer is a Node.js library that simplifies browser automation, perfect for tasks like testing and scraping. Here's what you'll learn:

Direct integration on Latenode: Learn how Latenode enhances web scraping workflows with a direct integration with Puppeteer-based Headless Browser and automation-friendly features. No need to pre-configure anything, just add the node and use in workflow automation!
Setup Requirements: Use Node.js 18+ and ensure your system meets the OS-specific dependencies.
Installation Options: Install Puppeteer with npm i puppeteer (includes Chrome for Testing) or npm i puppeteer-core (use your own browser).
Troubleshooting Tips: Fix Chromium launch errors, missing libraries, and dependency conflicts.
Advanced Configurations: Optimize performance, set up proxies, and manage environment variables.

Before we share a complete guide on issues in configuring Puppeteer, you should know that you can just skip it and use a direct, ready-made integration node on Latenode! Check it out:

Skip Configuring Puppeteer: Use Our Ready-Made Integration on Latenode

Latenode works seamlessly with Puppeteer to simplify browser automation. Below, we’ll explore Latenode's features and how to use a direct integration with Puppeteer for your automation needs.

Here’s a breakdown of Latenode’s main features:

Feature	Description	Benefit
Headless Browser	Puppeteer library integration	Direct browser control
AI Code Assistant	Automated code generation	Speeds up debugging and coding
No-code flexibility	300+ no-code integrations for tailored workflow adjustments	Extends Puppeteer functionality
NPM Package Support	Access to over 1 million packages	Boosts automation capabilities

"What I liked most about Latenode compared to the competition is that I did have the ability to write code and create custom nodes." - Germaine H., Founder Information Technology [3]

Latenode Tools

Latenode offers integration with the Headless Browser node, which is based on Puppeteer and allows you to add code directly into the editor and use it for tasks such as scraping all available information from a website, taking screenshots of pages, filling out forms, and generally anything that Puppeteer supports.

To find this integration, simply navigate to the Code Integrations folder in the node library, where you'll find the Headless Browser node. Add it to your script, click on it, and an editor will open where you can add code of any complexity and length. Additionally, you can specify the address, login, and password of your Proxy in the settings.

Connecting Puppeteer-Based Headless Browser to Other Integrations

But one node is not enough for automation. For greater customization, add a trigger and another action. For example, a webhook trigger and response to monitor exchange rate changes at the Bank of England, as we show in the guide above. Here's a scenario:

SCENARIO

Why Choose Latenode Integration Over VPS-Based Solution?

"Latenode blows away the competition with 99% uptime, affordable execution-based pricing, and a user-friendly interface." - Hammad Hafeez [3]

Latenode’s pricing is based on execution time rather than individual tasks, making it a budget-friendly option for large-scale Puppeteer automation. This platform allows developers to focus on creating robust workflows without worrying about excessive costs.

To maximize efficiency, you can use Latenode's интеграцию с Javascript, а также более чем 300 интеграциями с базами данных, CRM, project management tools, and AI models like Claude, ChatGPT, and Gemini. There’s a lot of potential usecases: automated outreach, database management, web scraping, etc. By combining Latenode and Puppeteer, you can centralize and streamline your automation processes.

sbb-itb-23997f1

If you still want a guide on fixing Puppeteer problems, check out the breakdown below.

Failed to Launch Chromium on VPS? Install missing dependencies on VPS puppetter

Before You Start

Before installing Puppeteer, make sure your setup meets the necessary dependencies to ensure smooth installation and operation.

Node.js Setup

Puppeteer requires Node.js to run. The latest versions of Puppeteer work with Node.js version 18 or higher, which aligns with the current LTS release.

To check your Node.js version, use this command:

node --version

If your version is below 18, update Node.js before continuing. Using the latest LTS version is strongly recommended. After confirming your Node.js version, check your system's operating system requirements.

System Requirements

The system requirements for Puppeteer depend on the operating system you're using. Here's a quick overview:

Operating System	Architecture	Required Components	Approx. Download Size
Windows	x64	Chrome for Testing	~280MB
macOS	x64, arm64	Chrome for Testing	~170MB
Debian/Ubuntu	x64	Chrome for Testing + Libraries	~282MB

When installing Puppeteer, it will automatically download a compatible version of Chrome for Testing. The download size varies depending on your OS (~280MB for Windows, ~170MB for macOS, and ~282MB for Debian/Ubuntu Linux) [1].

For Linux users, particularly on Debian/Ubuntu, you’ll need to install some additional libraries. Use the following command:

apt-get install -y libx11-xcb1 libxcomposite1 libxcursor1 libxdamage1 libxi6 libxtst6 libnss3 libcups2 libxss1 libxrandr2 libasound2 libatk1.0-0 libgtk-3-0

Here are some extra tips for specific environments:

AWS EC2 Amazon Linux: Enable the EPEL repository and install Chromium before setting up Puppeteer.
Docker Environments: Add the required shared libraries and Chromium package to your Dockerfile.
TypeScript Projects: Use TypeScript version 4.7.4 or higher to access Puppeteer’s latest type definitions and improve IDE support.

Basic Installation Steps

Once you've confirmed your Node.js setup and system requirements, you can install Puppeteer using npm.

npm Installation Guide

You have two ways to install Puppeteer through npm:

Standard Installation: This option automatically downloads Chrome for Testing:
```
npm i puppeteer
```
Core Installation: Use this if you want to manage browsers separately and skip downloading Chrome for Testing:
```
npm i puppeteer-core
```

With the standard installation, Chrome for Testing and the chrome-headless-shell binary are downloaded to $HOME/.cache/puppeteer. Check the System Requirements section for details on download sizes.

Once installed, you're ready to test your setup.

Testing Your Setup

Start by creating a file named test.js and add the following script:

<span class="hljs-keyword">const</span> puppeteer = <span class="hljs-built_in">require</span>(<span class="hljs-string">'puppeteer'</span>);

(<span class="hljs-title function_">async</span> () => {
  <span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>();
  <span class="hljs-keyword">const</span> page = <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">newPage</span>();
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">'https://www.google.com'</span>);
  <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Page title:'</span>, <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">title</span>());
  <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">close</span>();
})();

Run the script with:

node test.js

If the script runs successfully and displays the page title, your installation is working correctly.

Troubleshooting Tips

Linux users: Use your package manager to ensure all required dependencies are installed.
Windows users: Verify that Chrome's sandbox permissions are correctly configured.
If Chrome isn't found in its default location, set the PUPPETEER_CACHE_DIR environment variable to point to the correct installation directory.

"Running without a sandbox is strongly discouraged. Consider configuring a sandbox instead." [2]

For better stability and easier maintenance, you can create a .puppeteerrc.cjs file to configure Puppeteer's behavior instead of passing arguments directly to the launch method.

Fixing Chromium Issues

Chromium problems often stem from missing libraries or incorrect settings.

Using Local Chromium

If you'd rather use an existing Chromium installation instead of downloading a new one, Puppeteer can be set up to work with your local browser. This method is helpful if you need a specific Chromium version or handle browser installations manually.

To link Puppeteer with your local Chromium, adjust your launch settings like this:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({ <span class="hljs-attr">executablePath</span>: <span class="hljs-string">'/usr/bin/chromium-browser'</span> });

Make sure all necessary libraries are installed. On Linux, you can identify missing libraries with:

ldd chrome | grep not

If using a local installation isn't an option, consider installing Chromium separately using the steps below.

Installing Chromium Separately

Starting with Puppeteer v20.0.0, Chrome for Testing is downloaded instead of Chromium.

Compatibility Overview:

Puppeteer Version	Browser Version	Download Size
v24.4.0	Chrome for Testing 134.0.6998.35	~170MB (macOS)
v24.3.1	Chrome for Testing 133.0.6943.141	~282MB (Linux)
v24.3.0	Chrome for Testing 133.0.6943.126	~280MB (Windows)

If you encounter a "Failed to launch chrome" error, try these fixes:

Check Dependencies: Install any missing libraries on Debian-based systems:

<span class="hljs-built_in">sudo</span> apt-get install -y libasound2 libatk1.0-0 libgbm-dev

Adjust Memory Settings: For Docker environments, either increase /dev/shm size or use the --disable-dev-shm-usage flag:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">args</span>: [<span class="hljs-string">'--disable-dev-shm-usage'</span>]
});

Set Navigation Timeouts: Avoid hangs by setting a custom navigation timeout, such as 60 seconds:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">setDefaultNavigationTimeout</span>(<span class="hljs-number">60000</span>); <span class="hljs-comment">// 60 seconds</span>

"Headless chrome(-ium) needs a lot of dependencies to work with, and puppeteer doesn't install them all." - savebreach.com

For environments like GitLab CI or cases where sandboxing is disabled (not recommended), include specific launch arguments:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">args</span>: [<span class="hljs-string">'--no-sandbox'</span>, <span class="hljs-string">'--disable-setuid-sandbox'</span>]
});

To bypass HTTPS-related warnings in recent Chrome versions, disable the HttpsFirstBalancedModeAutoEnable feature:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">args</span>: [<span class="hljs-string">'--disable-features=HttpsFirstBalancedModeAutoEnable'</span>]
});

Handling Dependencies

Managing dependencies effectively is crucial to avoid launch failures and unpredictable behavior. This section covers resolving version conflicts and keeping packages updated to prevent runtime errors.

Fixing Package Conflicts

Package conflicts often lead to errors like "Cannot find module 'puppeteer-core/internal/...'" or Chrome launch issues. Here's how to address these problems:

<span class="hljs-comment">// Example: Resolving version conflicts using package.json overrides</span>
{
  <span class="hljs-string">"overrides"</span>: {
    <span class="hljs-string">"ws"</span>: <span class="hljs-string">"^8.17.1"</span>,
    <span class="hljs-string">"debug"</span>: <span class="hljs-string">"^4.3.4"</span>
  }
}

Steps to troubleshoot:

Check Node.js Version: Make sure you're using Node.js 18 or higher. Older versions can lead to compatibility issues.
Verify System Libraries: On Linux, ensure all required system libraries are installed. Refer to the dependency list in the System Requirements section.
Review Chrome Policies: Chrome policies may conflict with Puppeteer's default --disable-extensions flag. Try launching without it:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">ignoreDefaultArgs</span>: [<span class="hljs-string">'--disable-extensions'</span>]
});

Once conflicts are resolved, update your packages to ensure continued stability.

Keeping Packages Updated

Regularly updating dependencies reduces security risks and ensures compatibility. Here's how to manage this process:

Track Dependencies

Use a simple table to monitor package versions, update dates, and their importance:

Package	Current Version	Last Updated	Required By
puppeteer	24.4.0	Mar 2024	Core functionality
ws	8.17.1	Feb 2024	WebSocket support
debug	4.3.4	Jan 2024	Logging system

Version Management

When updating, use semantic versioning ranges carefully. For critical dependencies, pin exact versions to avoid unexpected changes:

<span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"dependencies"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"puppeteer"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"24.4.0"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"puppeteer-core"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"24.4.0"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>

Troubleshooting Updates

Generate a detailed dependency report with:

npm list --all > dependency-report.txt

This report helps identify conflicts and problematic nested dependencies.

For environments like Docker or GitLab CI, ensure your configuration includes necessary system packages:

<span class="hljs-keyword">RUN</span><span class="language-bash"> apt-get update && apt-get install -y \
    chromium \
    libnss3 \
    libgconf-2-4 \
    libxss1</span>

Extra Settings

Fine-tune Puppeteer for advanced setups with these additional configurations.

Environment Variables

Environment variables let you adjust Puppeteer's behavior and override default settings.

Here are some key variables:

Variable	Purpose	Example Value
PUPPETEER_CACHE_DIR	Specifies a custom cache directory for browser downloads	/usr/local/cache/puppeteer
PUPPETEER_EXECUTABLE_PATH	Points to a specific browser executable	/usr/bin/chromium
HTTP_PROXY	Configures HTTP proxy settings	http://proxy.company.com:8080
HTTPS_PROXY	Configures HTTPS proxy settings	https://proxy.company.com:8443
NO_PROXY	Lists domains excluded from proxy use	localhost,127.0.0.1

For custom Chromium installations, define the executable path like this:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">executablePath</span>: process.<span class="hljs-property">env</span>.<span class="hljs-property">PUPPETEER_EXECUTABLE_PATH</span> || puppeteer.<span class="hljs-title function_">executablePath</span>()
});

Once environment variables are set, you can configure proxies to handle network restrictions effectively.

Proxy Configuration

To use a proxy server with Puppeteer, apply the following setup:

<span class="hljs-comment">// Launch Puppeteer with a proxy server and authentication</span>
<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">args</span>: [<span class="hljs-string">'--proxy-server=http://157.230.255.230:8118'</span>]
});

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">authenticate</span>({
  <span class="hljs-attr">username</span>: <span class="hljs-string">'proxyUser'</span>,
  <span class="hljs-attr">password</span>: <span class="hljs-string">'proxyPass'</span>
});

<span class="hljs-comment">// Optimize navigation with specific settings</span>
<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">'https://example.com'</span>, {
  <span class="hljs-attr">waitUntil</span>: <span class="hljs-string">'networkidle2'</span>,
  <span class="hljs-attr">timeout</span>: <span class="hljs-number">30000</span>
});

Include error handling to ensure robust performance in production:

<span class="hljs-keyword">try</span> {
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(url);
} <span class="hljs-keyword">catch</span> (error) {
  <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'Proxy connection failed:'</span>, error.<span class="hljs-property">message</span>);
  <span class="hljs-comment">// Add fallback logic or retry mechanism</span>
}

For corporate setups, export proxy settings in your terminal:

<span class="hljs-built_in">export</span> HTTP_PROXY=<span class="hljs-string">"http://proxy.company.com:8080"</span>
<span class="hljs-built_in">export</span> HTTPS_PROXY=<span class="hljs-string">"https://proxy.company.com:8443"</span>
<span class="hljs-built_in">export</span> NO_PROXY=<span class="hljs-string">"localhost,127.0.0.1,.company.internal"</span>

You can also validate proxy connections programmatically:

<span class="hljs-keyword">const</span> <span class="hljs-title function_">validateProxy</span> = <span class="hljs-keyword">async</span> (<span class="hljs-params">page</span>) => {
  <span class="hljs-keyword">try</span> {
    <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">'https://api.ipify.org?format=json'</span>);
    <span class="hljs-keyword">const</span> content = <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">content</span>();
    <span class="hljs-keyword">return</span> content.<span class="hljs-title function_">includes</span>(<span class="hljs-string">'ip'</span>);
  } <span class="hljs-keyword">catch</span> {
    <span class="hljs-keyword">return</span> <span class="hljs-literal">false</span>;
  }
};

This ensures your proxy setup is working correctly before proceeding.

Next Steps

Setup Checklist

Before starting with Puppeteer automation, make sure your environment is configured correctly. Use the script below to validate your setup:

<span class="hljs-comment">// Validation script for environment setup</span>
<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>();
<span class="hljs-keyword">const</span> page = <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">newPage</span>();
<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">validateEnvironment</span>();  <span class="hljs-comment">// Custom validation</span>
<span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">close</span>();

Setup Component	Verification Step	Common Issue
Node.js	Check version compatibility	Outdated Node.js version
Package.json	Verify "type": "module" entry	ES6 import errors
Chrome Installation	Test browser launch	Missing Chromium binary
Memory Settings	Check /dev/shm size in Docker	Browser crash on launch
Resource Management	Implement browser.close()	Memory leaks

Once your setup is verified, you can focus on improving your workflows for better automation results.

Getting Started Tips

Carriyo’s PDF system efficiently handled 10,000 shipment labels daily, achieving a p95 latency of 365ms [4]. To reach similar performance levels, consider these strategies:

Resource Management: Disable unnecessary features to save resources. For instance, launch Puppeteer with optimized settings:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">headless</span>: <span class="hljs-literal">true</span>,
  <span class="hljs-attr">args</span>: [<span class="hljs-string">'--disable-dev-shm-usage'</span>],
  <span class="hljs-attr">defaultViewport</span>: { <span class="hljs-attr">width</span>: <span class="hljs-number">1920</span>, <span class="hljs-attr">height</span>: <span class="hljs-number">1080</span> }
});

Error Handling: Use robust error recovery methods, such as try-catch blocks and custom error handlers tailored to specific issues.
Performance Optimization: Boost speed by:
- Caching frequently used data
- Intercepting network requests
- Running tasks in parallel
- Using Chrome DevTools to monitor performance

For more advanced automation, explore Latenode’s low-code workflow platform. It offers execution-based pricing and a range of features to simplify complex Puppeteer implementations [3].