How do I install Headless Chromium on my system?

Headless Chromium allows you to run Chrome browser without a graphical user interface, making it perfect for automated testing, web scraping, and server environments. This guide covers installation methods for all major operating systems.

Quick Installation Overview

| Platform | Method | Difficulty | |----------|--------|------------| | Linux | Package manager or direct download | Easy | | macOS | Homebrew or direct download | Easy | | Windows | Direct download or Chocolatey | Easy | | Docker | Pre-built containers | Easy |

Linux Installation

Ubuntu/Debian (Recommended)

# Update package list
sudo apt-get update

# Install required dependencies
sudo apt-get install wget gnupg

# Add Google's official signing key
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -

# Add Google Chrome repository
sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google-chrome.list'

# Update package list and install Chrome
sudo apt-get update
sudo apt-get install google-chrome-stable

CentOS/RHEL/Fedora

# Create repository file
sudo tee /etc/yum.repos.d/google-chrome.repo <<EOF
[google-chrome]
name=google-chrome
baseurl=http://dl.google.com/linux/chrome/rpm/stable/x86_64
enabled=1
gpgcheck=1
gpgkey=https://dl.google.com/linux/linux_signing_key.pub
EOF

# Install Chrome
sudo yum install google-chrome-stable
# or for newer systems:
sudo dnf install google-chrome-stable

Direct Download Method

# Download the latest stable version
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb

# Install using dpkg
sudo dpkg -i google-chrome-stable_current_amd64.deb

# Fix dependencies if needed
sudo apt-get install -f

Test Installation

# Basic headless run
google-chrome --headless --disable-gpu --dump-dom https://example.com

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

macOS Installation

Using Homebrew (Recommended)

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Google Chrome
brew install --cask google-chrome

# Verify installation
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version

Direct Download

1. Download Chrome from chrome.google.com
2. Drag to Applications folder
3. Run from terminal using the full path

Test Installation

# Basic headless run
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --headless --disable-gpu --dump-dom https://example.com

# Create an alias for convenience
echo 'alias chrome="/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome"' >> ~/.zshrc
source ~/.zshrc

# Now use the alias
chrome --headless --disable-gpu --remote-debugging-port=9222

Windows Installation

Direct Download (Recommended)

1. Download Chrome from chrome.google.com
2. Run the installer
3. Chrome will be installed to C:\Program Files\Google\Chrome\Application\

Using Chocolatey

# Install Chocolatey if not already installed
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install Chrome
choco install googlechrome

Test Installation

# Command Prompt
cd "C:\Program Files\Google\Chrome\Application"
chrome.exe --headless --disable-gpu --dump-dom https://example.com

# PowerShell
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --headless --disable-gpu --remote-debugging-port=9222

Docker Installation

Official Google Chrome Image

# Pull the official image
docker pull gcr.io/zenika-hub/alpine-chrome:latest

# Run with custom command
docker run --rm -it gcr.io/zenika-hub/alpine-chrome:latest --headless --disable-gpu --dump-dom https://example.com

Selenium Chrome Image

# Pull Selenium Chrome image
docker pull selenium/standalone-chrome:latest

# Run with web driver support
docker run -d -p 4444:4444 --shm-size="2g" selenium/standalone-chrome:latest

# Test with curl
curl http://localhost:4444/wd/hub/status

Custom Dockerfile

FROM alpine:latest

# Install Chrome
RUN apk add --no-cache \
    chromium \
    nss \
    freetype \
    harfbuzz \
    ca-certificates \
    ttf-freefont

# Add Chrome user
RUN addgroup -g 1000 chrome && \
    adduser -D -s /bin/sh -u 1000 -G chrome chrome

USER chrome

# Set Chrome path
ENV CHROME_BIN=/usr/bin/chromium-browser
ENV CHROME_PATH=/usr/lib/chromium/

ENTRYPOINT ["chromium-browser", "--headless", "--disable-gpu", "--disable-software-rasterizer", "--disable-dev-shm-usage"]

Essential Command Line Flags

Basic Flags

# Essential flags for headless mode
--headless                    # Run in headless mode
--disable-gpu                # Disable GPU acceleration
--no-sandbox                 # Disable sandbox (needed in Docker)
--disable-dev-shm-usage      # Disable /dev/shm usage

Debugging and Development

# Remote debugging
--remote-debugging-port=9222

# Save screenshots
--screenshot=/path/to/screenshot.png

# Set window size
--window-size=1920,1080

# Set user agent
--user-agent="Custom User Agent"

# Disable images for faster loading
--disable-images

Example Commands

# Take a screenshot
google-chrome --headless --disable-gpu --screenshot=/tmp/screenshot.png --window-size=1920,1080 https://example.com

# Generate PDF
google-chrome --headless --disable-gpu --print-to-pdf=/tmp/page.pdf https://example.com

# Extract page content
google-chrome --headless --disable-gpu --dump-dom https://example.com > page.html

# Run with custom user agent
google-chrome --headless --disable-gpu --user-agent="Mozilla/5.0 (WebScrapingBot)" --dump-dom https://example.com

Troubleshooting

Common Issues

Permission Denied (Linux)

# Fix permissions
sudo chmod +x /usr/bin/google-chrome

Sandbox Issues (Docker)

# Add --no-sandbox flag
docker run --rm -it gcr.io/zenika-hub/alpine-chrome:latest --headless --no-sandbox --disable-gpu

Font Issues

# Install additional fonts (Ubuntu/Debian)
sudo apt-get install fonts-liberation fonts-dejavu-core

Verification Commands

# Check Chrome version
google-chrome --version

# Test headless mode
google-chrome --headless --disable-gpu --dump-dom https://httpbin.org/json

# Check available flags
google-chrome --help

Integration with Programming Languages

Python (Selenium)

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

options = Options()
options.add_argument('--headless')
options.add_argument('--disable-gpu')
driver = webdriver.Chrome(options=options)

Node.js (Puppeteer)

const puppeteer = require('puppeteer');

const browser = await puppeteer.launch({
  headless: true,
  executablePath: '/usr/bin/google-chrome'
});

This comprehensive installation guide should help you get Headless Chromium running on any system for your web scraping and automation needs.