Private Instances

WebPagetest is available as a software package for installation and running of private instances. 


The latest release is 3.0

Easy Deployment (on EC2)

There is an EC2 AMI available for the WebPageTest server that provides a lot of benefits:
  • No configuration required (up and running in 5 minutes).
  • Automatically starts and stops EC2 test agents in all of the EC2 regions as needed.
  • Automatically updates to the latest server and agent code.

Manual Deployment

System Requirements

WebPageTest can be configured to run all on one system (with the web server and test machines all running on the same PC) or with separate systems for the web server and testers. 

Web Server

The Web Server can be any OS that supports PHP (Linux and Windows have both been tested).
  • Nginx (php-fpm recommended) or Apache 2.x+:
  • PHP 5.3.0 or later with the following modules:
    • gd
    • zip
    • zlib
    • mbstring
    • curl (if you want to use remote-storage like S3 and Google storage)
    • sqlite (if you want to be able to edit test labels)
  • ffmpeg 
    • Make available in the path (used to extract video thumbnail images)
    • For mobile agent video support it needs to be 1.x (Linux, Windows)
  • imagemagick (optional)
    • Necessary for mobile video processing if using the mobile Node.js agent
  • jpegtran (optional)
    • Make available in the path (used for displaying jpeg analysis)
  • exiftool (optional)
    • Make available in the path (used for displaying jpeg analysis)

Test Machine(s)

  • Windows (Vista or later) (if you use 64-bit you will need WebPagetest 2.9 or later to support traffic shaping)


The zip archive contains 2 folders.  The www folder is the web server software and the agent folder is for the Test Machine(s).  The configuration files in the archive have a .sample extension so if you are updating an existing install you can just overwrite the current files with the new ones from the archive.

New in the 2.8 release is a script that will check for common configuration issues.  It can be accessed at http://<your web server>/install

Web Server

  1. Configure Apache with the required modules and set to allow for .htaccess overrides.
    • A sample site configuration file might look like this:
      <Directory "/var/www/webpagetest">
              AllowOverride all
              Order allow,deny
              Allow from all
      <VirtualHost *:80>
              DocumentRoot /var/www/webpagetest
  2. If you will be using agents that upload .pcap files, consider setting upload_max_filesize and post_max_size to large values (10mb should be enough) and in php.ini.
  3. If you will be collecting Chrome dev tools traces, consider setting memory_limit to a large value or disabling the memory limit by setting it to -1.
  4. Using the PHP DSO handler mod_php can dramatically reduce the CPU required when working with large numbers of agents uploading results.
  5. Restart Apache to use new configuration settings.
  6. Copy the files from the www folder in the archive to the DocumentRoot location (e.g. /var/www/webpagetest).
  7. Grant the apache user read/write permissions to the following folders under the DocumentRoot:
    • tmp
    • dat
    • results
    • work/jobs
    • work/video
    • logs
  8. There are several settings files in the settings folder that can be used to configure the site.  Make a copy of all of the .sample files (removing the .sample extension) as a template for your configuration settings.  Most of the settings can be used as-is with the exception of locations.ini (particularly if you are configuring more than one test location).
  9. More information on configuring locations.ini is available here:   

Test Machine(s)

Fasterize has a powershell script that will automate agent installation as well as a perfplanet blog post describing how to use it. Otherwise, for manual installation:
  1. Install the browsers you want to use for testing
  2. Configure the test system to automatically log-on to an administrator account. The easiest and most reliable way for this to work is to use the autologon app from Microsoft Technet.
  3. Disable any screen savers (the desktop needs to remain visible for the video capture to work)
  4. Disable UAC (Vista or later - slide to "never notify")
  5. Uninstall IE Enhanced-Security Mode (Windows Server)
  6. Force windows to use a stable clock if running in a VM (particularly KVM)
    • /USEPMTIMER to boot.ini for XP or Server 2003
    • "bcdedit /set {default} useplatformclock true" from an administrator shell otherwise
  7. Configure Windows to boot directly to the desktop (Server 2012)
  8. Disable Shutdown Event Tracker (Windows Server - for convenience)
    • run gpedit.msc
    • Open "Computer Configuration\Administrative Templates\System"
    • Open "Display Shutdown Event Tracker"
    • Set it to disabled
  9. Copy the test software from the agent folder to the system (to "c:\webpagetest" for this example)
  10. For pre-Windows 8.1 (or server 2012 R2) test agents, Install the DUMMYNET ipfw driver
    • If you are installing on 64-bit Windows, right-click on  "testmode.cmd" in the c:\webpagetest\dummynet\64bit folder and select "Run as Administrator".  Reboot the system to enable testmode.  If you do not run this then traffic shaping will not work after a reboot.
    • Copy the files from either the webpagetest\dummynet\32bit or webpagetest\dummynet\64bit directory into the webpagetest\dummynet directory (depending on your OS)
    • Pull up the properties for the Network Adapter that is used to access the Internet
    • Click "Install"
    • Select "Service" and click "Add"
    • Click "Have Disk" and navigate to webpagetest\dummynet
    • Select the ipfw+dummynet service (and click through any warnings about the driver being unsigned)
  11. Windows 10, if testing with Microsoft Edge (work in progress):
    • Install Python 2.7 for all users to c:\Python27 (default install directory)
    • Install selenium from a cmd shell
      • c:\Python27\Scripts\pip install selenium
    • Install pyWin32 from the agent folder (may need to be run from an administrator command prompt)
    • Install Imagemagick
    • Install Windows Performance Toolkit (uncheck all of the other options from the adk setup)
  12. You need a separate machine/VM for each version of IE but the rest of the browsers can all be run on the same machine and share a machine with IE (tests will not run at the same time, they will alternate)
  13. Create a task scheduler task to run wptdriver.exe at logon:
    • Configure it to run with the highest privliges
    • Have it run at logon of the user account
    • Make sure it is not configured to terminate after 3 days (the default task scheduler configuration)
  14. Make a copy of the settings file (wptdriver.ini) based on the sample
    • wptdriver can automatically install Chrome and Firefox (and keep Firefox up to date). If you would prefer to manually install the browsers then remove the installer=... entry for each of the browsers you want tp manually install
    • Make sure the path to the browser executables are correct for your system (if you are automatically installing Chrome and Firefox they will only install after the first time you run wptdriver)
    • Configure the location to match the location defined on the server in locations.ini
    • Configure the location key to match the server in locations.ini
    • Make sure the available browsers in the ini file match the list defined in locations.ini in the browsers=x,y,z entry for the location.
  15. Launch wptdriver and let it install any software it needs to install (exit when it gets to "waiting for work").
  16. Reboot to make sure everything starts up correctly
If you connect a remote desktop to the test machine, make sure to reboot the machine when you are done, otherwise the desktop will remain locked and screen captures will not work.

Headless Servers (including Google Compute Engine)

Screen shots and video capture both require that the desktop be visible for testing.  Some servers have no video device available or resolution that is too low for using for testing.  In those cases the setup becomes a bit more complicated (but is still possible).  The test machine needs 2 user accounts and needs to run a RDP session to itself and run the testing inside of the RDP session which will give it a virtual display to use.  This can also be used as a security technique if you are not comfortable leaving the desktop unlocked at all times.

  1. Create 2 user accounts.  We'll call them "user" and "administrator".  The "user" account will be the one that is used at startup to create the RDP session and the "administrator" account is where testing will be run.  The "user" account doesn't need to be an admin account
  2. Set up the testing account:
    • Connect with RDP to the "administrator" account and set it up to run tests using the normal WPT configuration
    • Log out of the RDP session (don't just disconnect, log the user out but leave the system running)
    • Re-connect through RDP to the "administrator" account and make sure testing starts up and runs correctly automatically as soon as you connect
  3. Set up the RDP host account:
    • Connect with RDP to the "user" account
    • Configure autologon to log in to the "user" account automatically at startup.  I usually use the autologon app from Microsoft to do the configuration.
    • Connect with RDP to using the administrator account and have it remember the credentials (can't be localhost or because RDP will block those attempts but it allows which is still localhost)
    • Open a cmd shell
    • Store the administrator password for RDP using "cmdkey /generic:TERMSRV/ /user:administrator /pass:<adminpass>"
    • enter "mstsc /w:1920 /h:1200 /v:" and make sure it opens a RDP connection and starts testing (close the session after verifying it works)
    • Create a task scheduler task to run at logon of the "user" account that runs mstsc.exe with command line options "/w:1920 /h:1200 /v:"
Now when you reboot the server it should automatically log into the "user" account which will then RDP to the local instance with the "administrator" account and testing will run inside of the RDP session


The mobile agent instructions are available here.

EC2 Test Agents

We have prepared public AMI's for EC2 that can be used as WebPagetest testers that are configured dynamically through the instance user data. The images have all of the software needed on a test system installed and configured (including AVISynth for generating videos and dummynet for doing the traffic shaping).


The configuration of the test agents is done through user data strings when instances are started.


  • wpt_server - the web server where WebPagetest is running (required)
  • wpt_url - (Linux agents only) Base URL to the work directory for fetching.  i.e.
  • wpt_loc - The location name to use for wptdriver (optional - if not specified it will fall back to wpt_location or be built from the region - ec2-us-east for example)
  • wpt_location - The location name to use for URLBlast (optional - if not specified it will be built from the region and browser - ec2-us-east-IE8 for example).  wptdriver will append _wptdriver to this location ID if wpt_loc is not set.
  • wpt_key - secret key for the specified location (optional)
  • wpt_timeout - timeout setting for each test in seconds (optional, defaults to 60)
  • wpt_username - username for basic authentication with WPT server. Ignored if wpt_password is not specified. (optional)
  • wpt_password - password for basic authentication with WPT server. Ignored if wpt_username is not specified. (optional)
  • wpt_validcertificate - Ignored unless the scheme of the wpt_server is 'https' If the value is '0', the hostname and expiry of the certificate are not checked. If the value is '1', the CN of the WPT server SSL certificate must match the hostname specified in the wpt_server parameter, and the certificate must be valid. (optional, defaults to '0')

Example User Data string wpt_loc=Test wpt_key=xxxxx

Sample locations.ini

A sample locations.ini for the server is available that is configured with all of the available EC2 regions:

AMI Images

The wptdriver instances (IE 9, 10 and 11) must have a matching browser name in locations.ini for the version of IE in the AMI ("IE 9", "IE 10" or "IE 11").

The instances will automatically install the latest supported versions of Chrome and Firefox when they start up (and will automatically update while they are running)

Finding the Images (aka EC2 AMI search sucks)

If you are having trouble finding the AMI's for manual launching, it's because EC2's AMI search is pretty broken.  I've found this path to work:

  • Do NOT search for the AMI in the Images->AMIs interface
  • Go to Instances->Instances (or spot instances)
  • Launch Instance
  • Select "Community AMIs"
  • Check "Windows"
  • Put the AMI ID in the search box and hit enter

us-east (Virginia)

  • IE9/Chrome/Firefox/Safari - ami-83e4c5e9
  • IE10/Chrome/Firefox/Safari - ami-0ae1c060
  • IE11/Chrome/Firefox/Safari - ami-4a84a220
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly) - ami-ec9bba97

us-east-2 (Ohio)

  • IE9/Chrome/Firefox/Safari - ami-c86933ad
  • IE10/Chrome/Firefox/Safari - ami-55742e30
  • IE11/Chrome/Firefox/Safari - ami-c96933ac
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-67eaca02

us-west (California)

  • IE9/Chrome/Firefox/Safari - ami-03d6a263
  • IE10/Chrome/Firefox/Safari - ami-05eb9f65
  • IE11/Chrome/Firefox/Safari - ami-678afe07
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-3884ac58

us-west-2 (Oregon)

  • IE9/Chrome/Firefox/Safari - ami-03e80c63
  • IE10/Chrome/Firefox/Safari - ami-fdeb0f9d
  • IE11/Chrome/Firefox/Safari - ami-b4ab4fd4
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-794bac01

ca-central-1 (Canada Central)

  • IE9/Chrome/Firefox/Safari - ami-184efc7c
  • IE10/Chrome/Firefox/Safari - ami-13328077
  • IE11/Chrome/Firefox/Safari - ami-0345f767
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-edea5489

eu-west-1 (Ireland)

  • IE9/Chrome/Firefox/Safari - ami-2d5fea5e
  • IE10/Chrome/Firefox/Safari - ami-3b45f048
  • IE11/Chrome/Firefox/Safari - ami-a3a81dd0
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-886591f1

eu-west-2 (London)

  • IE9/Chrome/Firefox/Safari - ami-4ad6dc2e
  • IE10/Chrome/Firefox/Safari - ami-2dd5df49
  • IE11/Chrome/Firefox/Safari - ami-4bd6dc2f
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-93d1c0f7

eu-central (Frankfurt)

  • IE9/Chrome/Firefox/Safari - ami-879c85eb
  • IE10/Chrome/Firefox/Safari - ami-ec9b8280
  • IE11/Chrome/Firefox/Safari - ami-87f2ebeb
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-e62e8189

ap-northeast-1 (Tokyo)

  • IE9/Chrome/Firefox/Safari - ami-4ed6e820
  • IE10/Chrome/Firefox/Safari - ami-ebd3ed85
  • IE11/Chrome/Firefox/Safari - ami-2f221c41
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-9aad44fc

ap-northeast-2 (Seoul)

  • IE9/Chrome/Firefox/Safari - ami-b2e12fdc
  • IE10/Chrome/Firefox/Safari - ami-76e12f18
  • IE11/Chrome/Firefox/Safari - ami-15e52b7b
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-c21ec7ac

ap-southeast-1 (Singapore)

  • IE9/Chrome/Firefox/Safari - ami-f87ab69b
  • IE10/Chrome/Firefox/Safari - ami-ce78b4ad
  • IE11/Chrome/Firefox/Safari - ami-3e55995d
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-6ac45a09

ap-southeast-2 (Sydney)

  • IE9/Chrome/Firefox/Safari - ami-306c4853
  • IE10/Chrome/Firefox/Safari - ami-25644046
  • IE11/Chrome/Firefox/Safari - ami-e88eab8b
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-caa2bca9

ap-south-1 (Mumbai)

  • IE9/Chrome/Firefox/Safari - ami-7a86ec15
  • IE10/Chrome/Firefox/Safari - ami-bf80ead0
  • IE11/Chrome/Firefox/Safari - ami-d498f2bb
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-64a7dc0b

sa-east (Sao Paulo)

  • IE9/Chrome/Firefox/Safari - ami-79c54515
  • IE10/Chrome/Firefox/Safari - ami-7cc54510
  • IE11/Chrome/Firefox/Safari - ami-203abb4c
  • Linux (Chrome, Chrome Beta, Chrome Canary, Firefox, Firefox Nightly- ami-de7305b2

Updating Test Agents

The test agents will automatically update their code from the server if there are update files in place (in /work/update on the server).  Each update consists of a zip file (the actual updata) and an ini file that contains some meta-data about the update (most importantly, the software version).  There are separate updates for the IE agent ( and the Chrome/Firefox agent (

Each new release includes updated agent binaries but sometimes it is helpful or necessary to update the agents in between releases if you need a bug fix or functionality that has been made available on the public instance but that hasn't been packaged up in a new release yet.  In this case you can download the update from the public instance of WebPagetest and deploy it on your private instance (the agents are backwards compatible so you do not need to update the web code unless you need updated functionality there).  

With WebPageTest 2.18 or later, the server can automatically update to the latest version as it is released.  In settings/settings.ini on the server, add:


To download and update manually:
After uploading the updates, each agent will automatically download and install the update before running their next test so you can be guaranteed that the update will be deployed before any more testing occurs.


Web Server

  • Waiting at the front of the queue
    • Commonly the issue is in your locations.ini. Double check that your location settings match that of which your agent is pulling the server with. Also note if you're using a key, do they match. You can check your Apache access logs for incoming requests being made by your test agent. 
  • The test completed but there were no successful results
    • If you're using a 64-bit Windows client you will be unable to perform traffic shaping (using dummynet.) In your locations.ini, add connectivity=LAN to the test location.
  • Waterfall charts are missing
    • Check if the GD library is installed. The GD library is used for drawing the waterfalls and generating thumbnail images.
    • Look to see if php-zip, php5-zip or a similar zip library is installed. With some default PHP distributions the library is not present.
  • Screen captures are black
    • When disconnecting from RDP, try rebooting the instance versus disconnecting from the RDP client. RDP locks up the desktop when you disconnect which will cause the screen shots and video to break.
  • Error message like this in /var/log/apache2/error.log:
    • [Mon Apr 30 10:18:14 2012] [error] [client] PHP Warning: POST Content-Length of 22689689 bytes exceeds the limit of 8388608 bytes in Unknown on line 0
    • PHP enforces a limit on the size of uploaded files, and an agent is uploading something larger than this limit. Change upload_max_filesize and post_max_filesize to larger values in php.ini.

Test Agent

  • Low disk space
    • WebPagetest doesn't maintain any temporary files but sometimes Windows itself leaves stuff lying around and the disks can fill up. When that happens there are a few common things you can do to clean it up:
      • You can delete everything in "C:\Windows\SoftwareDistribution\Download". Windows keeps the full installer for every software update it installs and it doesn't need them after the install.
      • Try right-clicking on the c drive -> properties -> Disk Cleanup. There might be some crash reports it can cleanup
    • If that doesn't free enough space there are a few more things you can do:
      • Use windirstat to see what is taking up the disk space
      • It's possible the IE temporary Internet files got corrupt and is growing out of control. CCleaner can help fix that sometimes
      • Make sure hibernation is disabled (no hiberfile.sys on the c drive)
      • Worst case, you can disable the swap file to get back a gig or two