Documentation / Installation



You can run using our Docker containers or using NodeJS.

Docker #

We have Docker images with, Chrome, Firefox, Xvfb and all the software needed for recording a video of the browser screen and analyse it to get Visual Metrics. It is super easy to use). Here’s how to use the container with both Firefox & Chrome (install Docker first).

Mac & Linux #

docker run --rm -v "$(pwd):/" sitespeedio/ -b firefox

Windows #

C:\Users\Vicky> docker pull sitespeedio/
C:\Users\Vicky> docker run --rm -v ${pwd}:/ sitespeedio/ -b firefox

That will output the data from the run in the current directory. You can read more about running the containers here.

Node JS #

Mac #

To be able to record a video of the screen and analyse the video, you need a couple of extra software except

You need: FFmpeg, ImageMagick 6 and pillow.

Install on a fresh Apple Mac M1:

  1. Install Homebrew
  2. Install latest NodeJS LTS (and npm). Either download it from or install using Homebrew: brew install node@14
  3. Make sure you can install using npm without using sudo. Checkout Sindre Sorhus guide.
  4. Install ImageMagick 6 brew install imagemagick@6
  5. Install ffmpeg brew install ffmpeg
  6. Install Python and Python dependencies (Python best practices) (or make sure you use the pre-installed Python 3):
    1. brew install pyenv
    2. pyenv install 3.9.1
    3. pyenv global 3.9.1
    4. echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init -)"\nfi' >> ~/.zshrc
    5. source ~/.zshrc
    6. curl --output
    7. python --user
    8. python -m pip install --user pillow
  7. To be able to throttle the connection without adding a sudo password you need to run: echo "${USER} ALL=(ALL:ALL) NOPASSWD:ALL" | sudo tee "/etc/sudoers.d/sitespeedio"
  8. If you plan to run the iOS Simulator, you also need to install Xcode. Either do it from the App store, follow Mac Stadiums guide or download directly from Verify that Xcode work by running xcrun simctl list devices to list your devices.
  9. If you want to run test on Android devices, you also need ADB. Install it using Homebrew like this: brew install --cask android-platform-tools

Now you are ready to install

npm install -g

After that you can also install the browsers that you need for your testing: Chrome/Firefox/Edge.

Linux #

If you are using Ubuntu you can use our prebuilt script. It will install all dependencies that you need to run including latest Firefox and Chrome. Use it if you have a new machine or just setup a new cloud instance. It will also create a new user sitespeedio that you will use to run The script will ask for a new password for that user:

bash <(curl -sL

If you use Debian you can use (installs Firefox ESR and you might want to upgrade that):

wget -O - | bash

When it’s finished you can try running --xvfb -b chrome --video --visualMetrics

You can also install everything manually to have more control. This is what’s needed on Ubuntu 20.04:

  1. Install NodeJS LTS
    • curl -sL -o
    • sudo bash
    • sudo apt install -y nodejs
  2. Install imagemagick and ffmpeg sudo apt-get update -y && sudo apt-get install -y imagemagick ffmpeg
  3. Install Python dependencies:
    • sudo apt-get install -y python-is-python3 python3-dev python3-pip
    • python -m pip install pyssim
  4. Install xvfb: sudo apt-get install -y xvfb
  5. Install ip and route for network throttling to work: sudo apt-get install -y net-tools iproute2
  6. Create a user that you will use to run and switch to that user:
    • adduser sitespeedio
    • usermod -aG sudo sitespeedio
    • su - sitespeedio
  7. Make sure that user can use sudo without password: echo "sitespeedio ALL=(ALL:ALL) NOPASSWD:ALL" | sudo tee "/etc/sudoers.d/sitespeedio"
  8. Make sure you can install using npm without using sudo. Checkout Sindre Sorhus guide.
  9. Install EDGEDRIVER_VERSION=89.0.723.0 npm install -g

Before you start your testing you need to install a browser. Here’s how you can install Firefox.

sudo apt install firefox -y

And if you want to use Chrome you can install it like this:

wget -q -O - | sudo apt-key add -
sudo sh -c 'echo "deb [arch=amd64] stable main" >> /etc/apt/sources.list.d/google-chrome.list'
sudo apt update
sudo apt install -y google-chrome-stable

Try it out with Firefox: -n 1 -b firefox --video --visualMetrics --xvfb

Or with Chrome: -n 1 -b chrome --video --visualMetrics --xvfb

Windows #

Checkout our GitHub action running in Windows to see how to install the dependencies needed.

If you run on Windows you can run tests on Firefox, Chrome and Edge.

Skip installing ChromeDriver/GeckoDriver/EdgeDriver #

If you don’t want to install ChromeDriver, EdgeDriver or GeckoDriver when you install through npm you can skip them with an environment variable.

Skip installing ChromeDriver:


Skip installing GeckoDriver:


Skip installing EdgeDriver:

EDGEDRIVER_SKIP_DOWNLOAD=true npm install -g

Updating ChromeDriver/GeckoDriver/EdgeDriver #

Using Docker the browser and driver is bundled with the correct versions. If you install everything yourself you may need to update driver versions.

Since the ChromeDriver team decided that a ChromeDriver version needs to match a browser version, it has been more work to test other Chrome versions.

You can download the ChromeDriver yourself from the Google repo and use --chrome.chromedriverPath to help Browsertime find it or you can choose which version to install when you install with a environment variable: CHROMEDRIVER_VERSION=81.0.4044.20 npm install

You can also choose versions for Edge and Firefox with EDGEDRIVER_VERSION and GECKODRIVER_VERSION.