1) Introduction
Speedtest CLI is the official command-line interface provided by Ookla for measuring internet performance directly from a terminal. It uses the same global testing infrastructure and methodology as the Speedtest web UI, enabling consistent and reliable measurement of:
- Download throughput
- Upload throughput
- Latency and jitter
- Packet loss (on supported tests)
Why and when to use Speedtest CLI
Speedtest CLI is especially useful when:
- Testing network performance on headless servers (cloud VMs, bare metal, appliances)
- Verifying ISP bandwidth commitments
- Diagnosing latency, routing, or congestion issues
- Automating periodic network health checks
- Comparing performance across data centers, racks, or regions
Key features
- Official Ookla engine (not a third-party reimplementation)
- Works without a graphical interface
- JSON output for automation and monitoring
- Server selection and filtering
- IPv4/IPv6 testing support
- Minimal runtime dependencies
2) Supported OS and Installation Overview
Speedtest CLI is distributed as native packages for major operating system families. Ookla maintains official repositories for Linux and integrates with FreeBSD’s package system.
Supported platforms covered in this guide:
- Ubuntu / Debian
- Fedora / CentOS / Red Hat Enterprise Linux
- FreeBSD
3) Installation by Operating System Family
A) Ubuntu / Debian
Supported releases include modern LTS and stable versions of Ubuntu and Debian. Installation is done via an official APT repository.
Prerequisites
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
Repository setup (recommended method)
# Add Ookla GPG key
curl -fsSL https://packagecloud.io/ookla/speedtest-cli/gpgkey \
| sudo gpg --dearmor -o /usr/share/keyrings/speedtest.gpg
# Add Speedtest CLI repository
echo "deb [signed-by=/usr/share/keyrings/speedtest.gpg] \
https://packagecloud.io/ookla/speedtest-cli/ubuntu/ $(lsb_release -cs) main" \
| sudo tee /etc/apt/sources.list.d/speedtest.list
# Update metadata and install
sudo apt-get update
sudo apt-get install -y speedtest
Verify installation
speedtest --version
speedtest
Note: On unsupported or very new distributions, the repository may not yet have metadata. In such cases, Ookla recommends using the direct binary download for your architecture.
B) Fedora / CentOS / Red Hat Enterprise Linux
Supported via DNF or YUM using an official RPM repository.
Fedora (DNF-based)
sudo dnf install -y curl
sudo dnf config-manager --add-repo \
https://packagecloud.io/ookla/speedtest-cli/rpm/speedtest-cli.repo
sudo dnf install -y speedtest
CentOS / RHEL / AlmaLinux / Rocky Linux
sudo yum install -y curl
sudo yum-config-manager --add-repo \
https://packagecloud.io/ookla/speedtest-cli/rpm/speedtest-cli.repo
sudo yum install -y speedtest
Verify installation
speedtest --help
speedtest
Compatibility note: Very old CentOS/RHEL releases may lack modern TLS or libc features required by current Speedtest binaries.
C) FreeBSD
FreeBSD provides Speedtest CLI through the official package repositories.
Install via pkg
sudo pkg update
sudo pkg install -y speedtest
Verify installation
speedtest --version
speedtest
FreeBSD packages are generally well-integrated and require no external repositories.
4) Migration Guidance (Bintray / Older Instructions)
Older Speedtest CLI instructions referenced Bintray, which was shut down and is no longer valid. Systems using legacy configurations must be cleaned up before installing the current version.
Ubuntu / Debian migration
# Remove old repository file
sudo rm -f /etc/apt/sources.list.d/speedtest.list
# Remove old package (if present)
sudo apt-get remove -y speedtest
# Refresh package cache
sudo apt-get update
Then follow the current APT installation steps above.
Fedora / CentOS / RHEL migration
# Remove old repo files if present
sudo rm -f /etc/yum.repos.d/bintray-ookla.repo
sudo rm -f /etc/yum.repos.d/speedtest.repo
# Remove old package
sudo yum remove -y speedtest
Reinstall using the official Packagecloud repository.
5) Practical Usage
Basic speed test
speedtest
List nearby servers
speedtest --list
Test against a specific server ID
speedtest --server 12345
Simple, human-readable output
speedtest --simple
JSON output (automation-friendly)
speedtest --json
# Save results to a file
speedtest --json > speedtest-result.json
Accept license non-interactively (useful for scripts)
speedtest --accept-license --accept-gdpr
6) Troubleshooting Common Issues
Frequent problems and solutions
| Issue / Symptom | Likely Cause | Resolution |
|---|---|---|
No match for argument: speedtest | Repository not added or metadata expired | Re-add repo, run package manager update |
Complete! This distribution version is not supported | OS release too new/old | Use direct binary build from Ookla |
| TLS / SSL errors | Missing CA certificates | Install ca-certificates |
| Very low speeds | CPU limits, VM shaping, or NIC offload | Check VM flavor, CPU steal, NIC settings |
| Hangs at “Selecting server” | Firewall or DNS blocking | Verify outbound TCP/UDP access |
Debug tips
# Check binary path
which speedtest
# Run with verbose output (if supported)
speedtest --help
7) Performance Considerations and Network Factors
- CPU contention on virtual machines can skew results
- Traffic shaping by hypervisors or ISPs may cap throughput
- Single-thread vs multi-thread behavior varies by server
- Geographic distance affects latency and achievable speed
- NIC offloading and MTU settings influence accuracy
For best results:
- Test multiple times
- Test against multiple servers
- Avoid running during peak load on the host
8) Security and Privacy Notes
- Speedtest CLI transmits performance data to Ookla servers
- Public IP address and test metadata are visible to the selected server
- Results may be logged by ISPs or enterprise firewalls
- Use caution when running on sensitive or regulated networks
For compliance-driven environments, ensure testing is permitted by policy.
9) Automation and Scripting Tips
Cron-based periodic testing
0 * * * * /usr/bin/speedtest --accept-license --accept-gdpr --json \
>> /var/log/speedtest.log
Parsing JSON output
- Integrate with monitoring tools (Prometheus exporters, ELK, etc.)
- Track trends in latency, jitter, and throughput
- Alert on sustained degradation
10) FAQ
Q1. Is Speedtest CLI free to use?
Yes, it is free for personal and operational testing, subject to Ookla’s license.
Q2. Does it work on headless servers?
Yes. No GUI or X11 dependencies are required.
Q3. Is this the same as speedtest-cli from Python?
No. This is the official Ookla binary, which is more accurate and actively maintained.
Q4. Can I force IPv6 or IPv4?
Yes, supported builds allow protocol selection via command options.
Q5. Why do results differ from browser tests?
Differences arise from TCP behavior, server choice, CPU limits, and routing.
Q6. Can I run it inside containers?
Yes, but container network modes and CPU limits can affect accuracy.
Q7. Is automation allowed?
Yes, but respect reasonable test frequency to avoid abuse.
11) References and Further Reading
Community operational guides and system administrator best practices
Ookla Speedtest CLI official documentation
Ookla license and GDPR notices
Linux distribution packaging guidelines (APT, DNF, pkg)