Documentation / Installation
Installation
You can install sitespeed.io using Docker or Node.js.
Using Docker
Docker images include sitespeed.io, browsers (Chrome, Firefox, Edge), and tools for video recording and analysis.
Example command (Mac & Linux)
docker run --rm -v "$(pwd):/sitespeed.io" sitespeedio/sitespeed.io https://www.sitespeed.io -b firefox Windows
C:\Users\Vicky> docker pull sitespeedio/sitespeed.io
C:\Users\Vicky> docker run --rm -v ${pwd}:/sitespeed.io sitespeedio/sitespeed.io https://www.sitespeed.io -b firefox That will write the result to sitespeed-result/www.sitespeed.io/<date-and-time>/ in the current directory. Open index.html in that folder to see the HTML report. You can read more about running the containers here.
Using Node.js
Requires additional software like FFmpeg and Python dependencies.
Pin the versions of all dependencies
sitespeed.io pins its own dependencies to exact versions, but the dependencies of those dependencies can resolve to newer versions within their ranges. With npm 11 and older, npm install sitespeed.io installs the exact dependency tree that we tested, from the npm-shrinkwrap.json in the package. npm 12 ignores that file, so with npm 12 you get the newest matching versions.
If you need the same versions on every run, use our Docker containers. They are built from our lockfile. If you install with npm, install sitespeed.io in its own project:
mkdir sitespeed && cd sitespeed
npm init -y
npm install --save-exact sitespeed.io Commit package.json and package-lock.json, install with npm ci and run with npx sitespeed.io https://www.sitespeed.io. Your lockfile then pins the versions that were the newest when you installed, not the versions that we tested.
To not install dependency versions that were published in the last days, set min-release-age in your .npmrc (npm 11.10 or later). For example min-release-age=7 skips versions that are newer than seven days.
Installation steps for Apple Mac M1
Install on a fresh Apple Mac M1:
- Install Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - Install the latest Node.js LTS (and npm). Either download it from nodejs.org or install using Homebrew (if you install using Homebrew, make sure you follow the instructions and add Node.js and npm to your PATH):
brew install node@24 - Make sure you can install using npm without sudo. Check out Sindre Sorhus's guide.
- Install ffmpeg
brew install ffmpeg - Install the Python dependencies needed for Visual Metrics. macOS ships Python 3, so use that:
On recent macOS versions, pip may refuse with "externally-managed-environment". If so, addpython3 -m pip install --user pillow pyssim opencv-python numpy scipy--break-system-packagesto the command above (or use a virtualenv). - 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" - If you plan to run the iOS Simulator, you also need to install Xcode. Either install it from the App Store, follow MacStadium's guide or download it directly from https://developer.apple.com/download/more/. Verify that Xcode works by running
xcrun simctl list devicesto list your devices. - If you want to run tests on Android devices, you also need ADB. Install it using Homebrew like this:
brew install --cask android-platform-tools - To be able to record a video you need to give access to Screen Recording for the Terminal App. You do that under Privacy settings.
Now you are ready to install sitespeed.io:
npm install sitespeed.io -g After that you can also install the browsers that you need for your testing: Chrome/Firefox/Edge.
Also test on iOS over USB
If you want to drive a real iPhone or iPad over USB from this Mac, three extra dependencies on top of the install above:
- Enable SafariDriver:
safaridriver --enable - Install
ios-webkit-debug-proxy(used by Browsertime for HAR capture):brew install ios-webkit-debug-proxy - The FFmpeg you installed in step 4 already covers video and visual metrics, nothing extra needed.
The phone-side setup (enable Remote Automation, trust the host, brightness/auto-lock) is documented in Test on iOS.
Linux
If you are using Ubuntu you can use our prebuilt script. It will install all dependencies you need to run sitespeed.io, including the latest Firefox and Chrome. Use it if you have a new machine or have just set up a new cloud instance. It will also create a new user sitespeedio that you will use to run sitespeed.io. The script has been tested on Ubuntu 24.04.
bash <(curl -sL https://gist.githubusercontent.com/soulgalore/18fbf40670a343fa1cb0606756c90a00/raw/7218332445010ee64e3301f2021bcf18a91f0627/install-sitespeed.io-and-dependencies-ubuntu.sh) If you use Debian (the script has been tested on Debian 12) you can use:
wget -O - https://gist.githubusercontent.com/soulgalore/2f070b0a150360053f7198a4e9067db1/raw/cc1c56577195832225ddc36460f6fc53510d6de3/install-sitespeed.io-and-dependencies-debian.sh | bash When it's finished you can try running sitespeed.io:
su - sitespeedio
sitespeed.io https://www.sitespeed.io --xvfb -b chrome --video --visualMetrics You can also install everything manually to have more control. This is what's needed on Ubuntu 24.04:
- Install Node.js LTS
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -sudo apt install -y nodejs
- Install ffmpeg
sudo apt-get update -y && sudo apt-get install -y ffmpeg - Install Python dependencies:
sudo apt-get install -y python-is-python3 python3-dev python3-pippython -m pip install pyssim opencv-python numpy scipy
- Install xvfb:
sudo apt-get install -y xvfb - Install ip and tc for network throttling to work:
sudo apt-get install -y net-tools - Create a user that you will use to run sitespeed.io and switch to that user:
adduser sitespeediousermod -aG sudo sitespeediosu - sitespeedio
- Make sure that user can use sudo without password:
echo "sitespeedio ALL=(ALL:ALL) NOPASSWD:ALL" | sudo tee "/etc/sudoers.d/sitespeedio" - Make sure you can install using npm without sudo. Check out Sindre Sorhus's guide.
- Install sitespeed.io:
npm install sitespeed.io --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. apt-key was deprecated in Ubuntu 22.04, so we use a per-repository keyring file with signed-by:
sudo install -d -m 0755 /etc/apt/keyrings
wget -qO- https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /etc/apt/keyrings/google-chrome.gpg
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/google-chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /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:
sudo install -d -m 0755 /etc/apt/keyrings
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /etc/apt/keyrings/microsoft.gpg
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/microsoft.gpg] https://packages.microsoft.com/repos/edge stable main" | sudo tee /etc/apt/sources.list.d/microsoft-edge.list
sudo apt-get update
sudo apt-get install -y microsoft-edge-stable Try it out with Firefox:
sitespeed.io -n 5 -b firefox https://www.sitespeed.io --video --visualMetrics --xvfb --browsertime.flushDNS true --connectivity.engine throttle -c cable Or with Chrome:
sitespeed.io -n 5 -b chrome https://www.sitespeed.io --video --visualMetrics --xvfb --browsertime.flushDNS true --connectivity.engine throttle -c cable Or with Edge:
sitespeed.io -n 5 -b edge https://www.sitespeed.io --video --visualMetrics --xvfb --browsertime.flushDNS true --connectivity.engine throttle -c cable Windows
Check out our GitHub Action running in Windows to see how to install the dependencies you need.
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.
Whether you use Raspberry Pi OS Lite or Desktop, you should do the following:
- Write the latest version of Raspberry Pi OS Lite or Raspberry Pi OS Desktop to an SD card. If you use the Raspberry Pi Imager, make sure to enable SSH and choose a username/password in the settings.
- Access your device using SSH.
- Install Node.js. Install the latest LTS; at the time of writing, that's version 24.
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install nodejs - Install ADB and Chromedriver.
sudo apt-get update
sudo apt-get install chromium-chromedriver adb -y - Install video and visual metrics dependencies.
sudo apt-get update && sudo apt-get install -y ffmpeg
python -m pip install pyssim opencv-python numpy scipy --break-system-packages - Follow the instructions from npm how to install without sudo.
- And then install sitespeed.io.
npm install sitespeed.io --location=global -
(Optional) You probably want to use gnirehtet to reverse-tether traffic from the phone back 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 at https://github.com/Genymobile/gnirehtet/blob/master/DEVELOP.md for how to build it for Raspberry Pi.
-
(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 the Pi itself. You do that by cloning the Geckodriver repo and building the version you want. Check out how it's done at https://github.com/jamesmortensen/geckodriver-arm-binaries and adapt it to your Raspberry Pi.
-
(Optional) If you are using Raspberry Pi 5 OS Desktop you can install scrcpy. Here's how to use it together with a Mac. First install scrcpy by building it on the Raspberry Pi, following the instructions at https://github.com/Genymobile/scrcpy/blob/master/doc/linux.md#latest-version.
Then you need to enable the VNC server. Do it by running:
sudo raspi-config Choose option 3. and then 3. again (VNC).
Reboot your device:
sudo reboot On your Mac, use "VNC Viewer" and use raspberrypi.local as the hostname. You will then be able to see the Raspberry Pi screen on your Mac. Start scrcpy and you will see the phone screen too.
- Plug in your phone, allow USB debugging on it and run sitespeed.io:
sitespeed.io https://www.sitespeed.io --android -n 1 --video --visualMetrics ChromeDriver/GeckoDriver/EdgeDriver
Installing sitespeed.io does not download ChromeDriver, EdgeDriver or GeckoDriver. Browsertime downloads the driver the first time a test needs it, into the vendor folder of the driver package in node_modules. The machine that runs the test must then be able to reach the download host and write to node_modules.
If you build your own Docker or CI image, or the test machine has no internet access, install the drivers after npm install:
node node_modules/@sitespeed.io/chromedriver/install.js
node node_modules/@sitespeed.io/geckodriver/install.js
node node_modules/@sitespeed.io/edgedriver/install.js For a global install, run the scripts from the node_modules folder of the global install (npm root -g).
Updating ChromeDriver/GeckoDriver/EdgeDriver
When using Docker, the browser and driver are bundled with the correct versions. If you install everything yourself, you may need to update driver versions.
You can download ChromeDriver yourself from Chrome for Testing and use --chrome.chromedriverPath to help Browsertime find it. You can also choose which version to install with an environment variable when you run the install script: CHROMEDRIVER_VERSION=131.0.6778.85 node node_modules/@sitespeed.io/chromedriver/install.js
You can also choose versions for Edge and Firefox with EDGEDRIVER_VERSION and GECKODRIVER_VERSION. To use an Edgedriver or Geckodriver that you already have, use --edge.edgedriverPath or --firefox.geckodriverPath.