What are the command-line arguments to launch Headless Chromium?

To launch Chromium (or Google Chrome) in headless mode via the command line, you need specific command-line arguments. Headless mode runs the browser without a graphical user interface, making it ideal for automated tasks, testing, and server environments.

Basic Command Structure

Here are the essential command-line arguments to launch headless Chromium:

chromium --headless --disable-gpu --remote-debugging-port=9222 http://example.com

Essential Arguments Explained

Core Arguments

--headless: Enables headless mode (runs without GUI)
--disable-gpu: Disables GPU hardware acceleration (required for stability in headless mode)
--remote-debugging-port=9222: Opens debugging protocol on port 9222 for programmatic control
http://example.com: Optional URL to navigate to on startup

Security Arguments

--no-sandbox: Disables the security sandbox ⚠️ Use with caution - reduces security
--disable-web-security: Disables web security features ⚠️ Only for development/testing
--disable-features=VizDisplayCompositor: Prevents certain rendering issues

Recommended Production Command

For production environments, use this secure configuration:

chromium --headless --disable-gpu --disable-dev-shm-usage --no-first-run --disable-extensions --disable-default-apps --remote-debugging-port=9222

Additional Useful Arguments

--disable-dev-shm-usage: Prevents shared memory issues in Docker containers
--no-first-run: Skips first-run experience
--disable-extensions: Disables all extensions
--disable-default-apps: Disables default applications
--window-size=1920,1080: Sets viewport size for screenshots
--user-data-dir=/tmp/chrome-user-data: Specifies custom user data directory

Platform-Specific Examples

Windows

"C:\Program Files\Google\Chrome\Application\chrome.exe" --headless --disable-gpu --remote-debugging-port=9222 http://example.com

macOS

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --headless --disable-gpu --remote-debugging-port=9222 http://example.com

Linux (Ubuntu/Debian)

google-chrome --headless --disable-gpu --remote-debugging-port=9222 http://example.com

Linux (Chromium)

chromium-browser --headless --disable-gpu --remote-debugging-port=9222 http://example.com

Docker Environment Example

For containerized environments, use these additional flags:

chromium --headless --disable-gpu --disable-dev-shm-usage --no-sandbox --disable-setuid-sandbox --remote-debugging-port=9222

Testing Connection

After launching with --remote-debugging-port=9222, verify the connection:

curl http://localhost:9222/json/version

Web Scraping Integration

With Puppeteer (Node.js)

const puppeteer = require('puppeteer');

const browser = await puppeteer.launch({
  headless: true,
  args: [
    '--disable-gpu',
    '--disable-dev-shm-usage',
    '--no-sandbox',
    '--disable-setuid-sandbox'
  ]
});

With Selenium (Python)

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

chrome_options = Options()
chrome_options.add_argument('--headless')
chrome_options.add_argument('--disable-gpu')
chrome_options.add_argument('--no-sandbox')

driver = webdriver.Chrome(options=chrome_options)

Security Best Practices

Avoid --no-sandbox in production when possible
Use isolated user data directories with --user-data-dir
Limit network access with firewall rules
Run in containers for additional isolation
Use specific port ranges for debugging protocols

Troubleshooting Common Issues

Crashes on startup: Add --disable-dev-shm-usage and --no-sandbox
Memory issues: Use --max_old_space_size=4096 for Node.js applications
Font rendering problems: Install fonts or use --disable-font-subpixel-positioning
Docker issues: Ensure container has sufficient shared memory (--shm-size=2g)

For production web scraping, consider using higher-level libraries like Puppeteer, Playwright, or Selenium WebDriver, which handle these command-line arguments automatically and provide more robust APIs for browser automation.

Table of contents