Speedtest CLI is Ookla's official command-line client for speedtest.net. It measures latency, jitter, download and upload speed and packet loss from your server to a Speedtest server, which is a quick way to check whether a slow application is caused by the network. In this tutorial you will install Speedtest CLI on Ubuntu 24.04 or Debian 12, run a test, pick specific test servers and save the results in a machine-readable format.
Prerequisites
To follow this guide you need:
- A server running Ubuntu 24.04 LTS or Debian 12 on x86_64 or arm64, for example a CubePath VPS or dedicated server.
- A non-root user with
sudoprivileges. - Outbound internet access. A full test transfers several hundred megabytes, so avoid running it in a loop on a metered connection.
Step 1 - Removing the unofficial speedtest-cli package
Ubuntu and Debian ship a package called speedtest-cli, a third-party Python client that also installs a speedtest command. It is not Ookla's client, gives less accurate results on fast links and would conflict with the official binary. Check whether it is installed:
dpkg -l speedtest-cli
If the output shows a line starting with ii, remove it:
sudo apt remove speedtest-cli
Step 2 - Downloading the official Speedtest CLI
Ookla publishes Speedtest CLI as a static binary in a tarball. Check your architecture first:
uname -m
x86_64
Download the tarball that matches your architecture to a temporary directory. For x86_64:
cd /tmp
curl -fLO https://install.speedtest.net/app/cli/ookla-speedtest-1.2.0-linux-x86_64.tgz
For aarch64 (arm64) servers, download ookla-speedtest-1.2.0-linux-aarch64.tgz instead. You can check for newer releases on the Speedtest CLI page.
Extract the archive:
tar -xzf ookla-speedtest-1.2.0-linux-x86_64.tgz
The archive contains the speedtest binary and its documentation (speedtest.md and speedtest.5).
Step 3 - Installing the binary
Install the binary into /usr/local/bin, which is in every user's PATH, with the correct permissions:
sudo install -m 0755 speedtest /usr/local/bin/speedtest
Confirm the shell finds the right binary and check its version:
command -v speedtest
speedtest --version
/usr/local/bin/speedtest
Speedtest by Ookla 1.2.0.84 (ea6b6773cf) Linux/x86_64-linux-musl 6.8.0-45-generic x86_64
The official command line client for testing the speed and performance of your internet connection.
You can now delete the downloaded files:
rm /tmp/ookla-speedtest-1.2.0-linux-x86_64.tgz /tmp/speedtest /tmp/speedtest.md /tmp/speedtest.5
Step 4 - Running your first speed test
The first time you run Speedtest CLI it asks you to accept Ookla's license and GDPR notice. Accept both non-interactively with these flags (they are only needed once per user):
speedtest --accept-license --accept-gdpr
Speedtest picks the nearest server based on latency and runs the test. The output looks similar to this:
Speedtest by Ookla
Server: Adamo - Madrid (id: 1680)
ISP: CUBEPATH
Idle Latency: 8.92 ms (jitter: 0.10ms, low: 8.82ms, high: 8.98ms)
Download: 938.77 Mbps (data used: 1.1 GB)
9.01 ms (jitter: 1.95ms, low: 8.86ms, high: 31.79ms)
Upload: 937.72 Mbps (data used: 819.2 MB)
12.62 ms (jitter: 0.43ms, low: 8.84ms, high: 13.52ms)
Packet Loss: 0.0%
Result URL: https://www.speedtest.net/result/c/your_result_id
The key values are:
- Idle Latency: round-trip time to the test server with no load.
- Download / Upload: throughput in each direction, followed by the latency measured while the link was loaded. A big jump between idle and loaded latency points to congestion.
- Packet Loss: should be
0.0%. Any sustained loss is worth investigating. - Result URL: a link to the result on speedtest.net, useful to share with support.
Step 5 - Testing against a specific server
The automatically chosen server is not always the best reference. List the servers near you:
speedtest --servers
Closest servers:
ID Name Location Country
==============================================================================
1680 Adamo Madrid Spain
14979 Orange Espana Madrid Spain
Run the test against one of them with -s and its ID:
speedtest -s 14979
Testing against two or three different servers, ideally in different networks, tells you whether a low result is caused by your server or by one particular test server.
If your server has several IP addresses, choose the source address for the test with -i:
speedtest -i your_server_ip
Step 6 - Saving results as JSON or CSV
For scripts and monitoring, change the output format with -f. Supported formats include human-readable (the default), csv, tsv, json, jsonl and json-pretty:
speedtest -f json-pretty
In the JSON output, download.bandwidth and upload.bandwidth are reported in bytes per second. Multiply by 8 to get bits per second. With jq you can extract the values in Mbps:
sudo apt install jq
speedtest -f json | jq '{download_mbps: (.download.bandwidth*8/1e6), upload_mbps: (.upload.bandwidth*8/1e6), ping_ms: .ping.latency}'
{
"download_mbps": 938.77,
"upload_mbps": 937.72,
"ping_ms": 8.92
}
Troubleshooting
speedtest: error: unrecognized arguments or a different output format. The shell is running the unofficial Python client. Check command -v speedtest; if it does not point to /usr/local/bin/speedtest, remove the speedtest-cli package as shown in Step 1 and run hash -r.
Cannot read from socket or Configuration - Couldn't resolve host name. The server cannot reach speedtest.net. Check DNS resolution with getent hosts www.speedtest.net and make sure your firewall allows outgoing connections.
Results are much lower than expected. Make sure nothing else is using the network or CPU during the test (check with top), and repeat the test against several servers. A single slow test server is common. If low results persist, contact CubePath support and include the Result URLs.
Conclusion
You installed Ookla's official Speedtest CLI on Ubuntu 24.04 or Debian 12, ran tests against automatically chosen and specific servers, and exported the results as JSON. As next steps, use mtr to find where latency or packet loss appears along the path, or iperf3 between two of your own servers to measure bandwidth without depending on public test servers.