Skip to main content

​
Overview

The install command downloads and caches Chrome and ffmpeg binaries to ~/.webreel. Both are also automatically downloaded on first use, so this command is optional but useful for:
  • Pre-installing dependencies before recording
  • Fixing corrupted or incomplete downloads
  • Ensuring binaries are ready in CI/CD environments

​
Syntax

webreel install [options]

​
Options

OptionTypeDefaultDescription
--forcebooleanfalseDelete cached binaries and re-download them

​
Usage Examples

​
Install all dependencies

Download Chrome and ffmpeg if not already cached: 
webreel install
Output: 
Installing Chrome (headless shell), Chrome (full, for preview), ffmpeg...

Chrome (headless shell) ready: /home/user/.webreel/chrome-headless-shell/chrome-headless-shell
Chrome (full, for preview) ready: /home/user/.webreel/chrome/chrome
ffmpeg ready: /home/user/.webreel/ffmpeg/ffmpeg

All dependencies installed.

​
Force reinstall

Delete cached binaries and download fresh copies: 
webreel install --force
This is useful if:
  • Binaries are corrupted
  • Downloads were interrupted
  • You want to update to newer versions

​
Installed Components

​
Chrome Headless Shell

  • Location: ~/.webreel/chrome-headless-shell/
  • Purpose: Used by webreel record for fast, headless recording
  • Size: ~100-150MB
  • Platform: Downloads the correct binary for your OS (Linux, macOS, Windows)

​
Chrome (Full Browser)

  • Location: ~/.webreel/chrome/
  • Purpose: Used by webreel preview for visible browser debugging
  • Size: ~150-200MB
  • Platform: Downloads the correct binary for your OS

​
ffmpeg

  • Location: ~/.webreel/ffmpeg/
  • Purpose: Encodes raw frames into MP4, GIF, or WebM video files
  • Size: ~50-80MB
  • Platform: Downloads the correct binary for your OS

​
Download Behavior

​
Automatic detection

The install command automatically:
  • Detects your operating system (Linux, macOS, Windows)
  • Selects the appropriate architecture (x64, arm64)
  • Downloads compatible binaries

​
Progress indication

During download, you will see progress for each component. Downloads run in parallel to save time.

​
Caching

Once downloaded, binaries are cached and reused:
  • Subsequent runs of webreel record or webreel preview use cached versions
  • No re-download unless you use --force
  • Cache persists across terminal sessions

​
Environment Variable Overrides

You can skip downloads by pointing to existing binaries:

​
Chrome Headless Shell

export CHROME_HEADLESS_PATH=/usr/bin/chrome-headless-shell
webreel install
Output: 
Skipping Chrome (headless shell), using CHROME_HEADLESS_PATH=/usr/bin/chrome-headless-shell

​
Chrome Full Browser

export CHROME_PATH=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
webreel install

​
ffmpeg

export FFMPEG_PATH=/usr/local/bin/ffmpeg
webreel install

​
All overrides

If all three are set: 
export CHROME_HEADLESS_PATH=/usr/bin/chrome-headless-shell
export CHROME_PATH=/usr/bin/chrome
export FFMPEG_PATH=/usr/bin/ffmpeg
webreel install
Output: 
Nothing to install.

​
When to Use

​
Pre-installation for CI/CD

Run install before recording to avoid download delays: 
steps:
  - name: Install webreel dependencies
    run: npx webreel install
  
  - name: Record videos
    run: npx webreel record

​
Fix corrupted downloads

If recording fails with binary errors: 
webreel install --force
webreel record

​
Offline preparation

Download binaries while online, then record offline: 
webreel install
# Disconnect from network
webreel record  # Uses cached binaries

​
Docker images

Pre-install in Dockerfile to speed up container startup: 
RUN npx webreel install

​
Error Handling

​
Download failures

If a download fails: 
Chrome (headless shell) failed: Network error during download
ffmpeg ready: /home/user/.webreel/ffmpeg/ffmpeg

Failed to install: Chrome (headless shell)
The command:
  • Reports which components failed
  • Exits with code 1
  • Leaves successfully downloaded components cached
Retry with: 
webreel install

​
Insufficient disk space

Total required space: ~300-400MB If disk is full, you will see OS-level errors. Free up space and retry.

​
Cache Management

​
Cache location

All binaries are stored in: 
~/.webreel/
  chrome-headless-shell/
  chrome/
  ffmpeg/
  raw/           # Raw recordings
  timelines/     # Timeline data
  frames/        # Debug frames (if --frames used)

​
Clear cache

To remove all cached binaries: 
rm -rf ~/.webreel/chrome-headless-shell
rm -rf ~/.webreel/chrome
rm -rf ~/.webreel/ffmpeg
Then reinstall: 
webreel install

​
Update binaries

Currently, webreel does not auto-update. To get newer versions: 
webreel install --force
Run webreel install once after installing webreel to avoid delays during your first recording.
Chrome and ffmpeg are open-source and downloaded from official distribution channels. No webreel account or authentication is required.

Build docs developers (and LLMs) love

Get started for freeTalk to us