Documentation / Installation



You can run using our Docker containers or using NodeJS.

Docker #

We have Docker images with, Chrome, Firefox, Edge, 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@16
  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 OpenCV-Python Numpy
  4. Install xvfb: sudo apt-get install -y xvfb
  5. Install ip and tc for network throttling to work: sudo apt-get install -y net-tools
  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 npm install --location=global

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

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

 curl | gpg --dearmor > microsoft.gpg
 sudo install -o root -g root -m 644 microsoft.gpg /etc/apt/trusted.gpg.d/
 sudo sh -c 'echo "deb [arch=amd64] stable main" > /etc/apt/sources.list.d/microsoft-edge-dev.list'
 sudo apt-get update
 sudo apt-get install -y microsoft-edge-stable

Try it out with Firefox: -n 5 -b firefox --video --visualMetrics --xvfb --browsertime.flushDNS true --connectivity.engine throttle -c cable

Or with Chrome: -n 5 -b chrome --video --visualMetrics --xvfb --browsertime.flushDNS true --connectivity.engine throttle -c cable

Or with Edge: -n 5 -b edge --video --visualMetrics --xvfb --browsertime.flushDNS true --connectivity.engine throttle -c cable

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.

Raspberry Pi #

You can use your Raspberry Pi to run tests on your Android phone(s).

We have a pre-made image that you can use or follow the instructions below to create your own.

If you just want to run your test you can use Raspberry Pi OS Lite. If you also want to be able to see the phone screen on your desktop (for debugging) you can use Raspberry Pi OS Desktop.

Independent if you use Raspberry Lite/Desktop you should do the following:

  1. Write the latest version Raspberry Pi OS Lite/ Raspberry Pi OS Desktop on a SD card. If you use the Raspberry Pi Imager make sure to enable ssh and choose username/password in the settings.
  2. Access your device using ssh.
  3. Install NodeJS. Install latest LTS, when I write this that version is 16.15.1.
    curl -fsSL | sudo -E bash -
    sudo apt install nodejs
  4. Install ADB and Chromedriver.
    sudo apt-get update
    sudo apt-get install chromium-chromedriver adb -y
  5. Install video and visual metrics dependencies.
    sudo apt-get update && sudo apt-get install -y imagemagick ffmpeg
    python -m pip install pyssim OpenCV-Python Numpy
  6. Follow the instructions from npm how to install without sudo.
  7. And then install
    npm install --location=global
  8. (Optional) You probably want to use Gnirenhet to reverse tethering back the the traffic from the phone to the Raspberry Pi. That way you can throttle the connection on the Raspberry Pi and the phone will use the same connection. Follow the instructions on how to build for Raspberry Pi.

  9. (Optional) You need Geckodriver if you want to run tests using Firefox on your phone. The easiest way to get Geckodriver on your Raspberry Pi is to build it on that Pi. You do that by cloning the Geckodriver repo and build the version you want. Checkout how it’s done at and adapt it to your Raspberry.

  10. (Optional) If you are using Raspberry Pi OS Desktop you can install scrcpy and vnc. Here’s instructions how to use it together with a Mac. First install scrcpy:
    sudo apt-get update && sudo apt-get install -y scrcpy

    Then you need to enable vnc server.

    sudo systemctl enable vncserver-x11-serviced 

    Then generate a password that you will use to connect to VNC from your computer

    sudo vncpasswd -service

    Then setup auth by edit the file /etc/vnc/config.d/common.custom:

    sudo nano /etc/vnc/config.d/common.custom

    Add Authentication=VncAuth in the file and save and close. Restart the vnc server:

    sudo systemctl restart vncserver-x11-serviced

    As the last step, make sure to export your display number to the environment variable DISPLAY.

    echo 'export DISPLAY=:0' >> ~/.profile

    Reboot your device:

    sudo reboot

    On your Mac, open “Screen Sharing” and then use raspberrypi.local as the hostname and the password you set in the previous step. You will then be able to see the Raspberry PI screen on your Mac. Start scrcpy and you will see the phone screen too.

  11. Plugin your phone, “Allow USB debugging” on your phone and run --android -n 1 --video --visualMetrics

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.

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.