Installing and Configuring Puppeteer: Solving Common Dependency and Chromium Issues
Learn how to install and configure Puppeteer for browser automation, troubleshoot common issues, and optimize your setup for better performance.
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) ornpm 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 puppeteerCore 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_DIRenvironment 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-devAdjust Memory Settings: For Docker environments, either increase
/dev/shmsize or use the--disable-dev-shm-usageflag:<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-extensionsflag. 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].
Related posts
