How to open the browser in headful mode with Puppeteer

Puppeteer, created by Google, is a Node.js library offering an advanced API for managing both headless and headful browsers via the DevTools Protocol.

A headless browser is launched in the background without a visible GUI. A headful browser (also known as a full browser) is launched with a visible GUI, allowing us to see the browser window and interact with the browser as we normally interact with manually opened Chrome or any other browser.

Syntax

To launch a browser with Puppeteer, we use the puppeteer.launch() function. This function accepts multiple arguments, including headless argument whose default value is true. To run the browser in headful mode, we need to set it to false.

await puppeteer.launch({
headless: false,
args:["--no-sandbox"]
});

Note: We are passing the --no-sandbox argument to disable sandboxing to open the browser on the Educative platform. If you're running the script on your local machine, this argument might be unnecessary in your command.

The puppeteer.launch() function returns a PromisePromise is an object representing the eventual completion or failure of an asynchronous operation.. The await keyword is used within the async function to tell JavaScript to wait for the Promise to be resolved before proceeding to the next line of code.

Code example

Execute the following code example by clicking the “Run” button below the code and see the full browser launched in the “Output” tab.

Note: It may take a few seconds for the browser to open so please be patient. You may see the logs (messages printed with console.log()) in the "Terminal" tab.

const puppeteer = require('puppeteer');

(async () => {
  try {
    console.log("Opening the browser in headful mode...");
    await puppeteer.launch({
      headless: false,
      args:["--no-sandbox"]
    });
    console.log("Browser sucessfully opened in headful mode.");
  } catch (err) {
    console.log("Could not launch the browser instance => : ", err);
  }
})();
Running code example that opens the browser in headful mode

Code explanation

  • Line 1: We import the Puppeteer library using the require function in Node.js. This action loads the Puppeteer module, making all of its functionality accessible within the script under the variable name puppeteer.

  • Lines 3–14: We define an asynchronous function using the async keyword. This function is immediately invoked. Inside this function, we can use the await keyword to pause execution and wait for promises to resolve.

    • try{...} catch(error){...} code block is used for error handling. Code inside the try block is executed, and if any errors occur, they are caught by the catch block.

    • Inside the try block, on line 6, we launch the headful browser using Puppeteer. 

    • console.log statements indicate the progress and status of the browser launch process.

When to use the headful mode

The choice between headful and headless modes depends on the specific requirements of the task being performed. If visual inspection and manual interaction are important, headful mode is preferable, for example, in user interface testing, debugging, etc. Headless mode is often the better choice for automated, resource-efficient tasks, such as large-scale web scraping and automated testing. This is because running the browser in headful mode requires more resources due to the GUI and slows down task performance.

Free Resources

Copyright ©2025 Educative, Inc. All rights reserved