Testing your network performance doesn't require opening a browser or dealing with heavy web interfaces. Running a speedtest cli utility straight from your terminal gives you instant data on download speeds, upload bandwidth, and latency without browser bloat or script overhead. Whether you manage headless remote servers, configure headless Raspberry Pi nodes, or simply prefer keyboard-driven workflows, command-line diagnostic tools save time and offer scriptable output formats like JSON or CSV.
Two primary variants exist for testing bandwidth from the shell: the popular Python-based utility originally built by community developers, and the official command-line interface provided by Ookla. Both options allow you to benchmark network connections instantly, but they differ in installation paths, syntax, and internal testing methods. Knowing how to deploy, configure, and parse these tools ensures accurate diagnostics every time you run a check.
Choosing Your Variant: Community Python Script vs Official Ookla CLI
Before typing installation commands, you need to know which version fits your environment. The community package, widely known as speedtest-cli, runs via Python and communicates with speedtest.net infrastructure. It's lightweight and works on almost any system with a Python interpreter.
The official Ookla package, named simply speedtest, is a compiled binary package distributed directly by the creators of Speedtest.net. It uses pure socket tests, matches web-based results more closely, and provides enterprise-friendly reporting formats like CSV and JSONL.
If you're managing standard desktop Linux distributions or remote virtual private servers, the official binary is usually preferred for accuracy. If you're working inside restricted containers where adding external repositories isn't possible, the pip-installable Python package provides a convenient fallback.
Installing the Official Ookla CLI on Linux and macOS
Deploying the official binary ensures your diagnostics align with standard web portal measurements. The installation process varies depending on your operating system package manager.
Installation on Ubuntu and Debian
For Debian and Ubuntu environments, you add the official package repository via script, update your local index, and install the package:
curl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.deb.sh | sudo bash
sudo apt-get install speedtest
Installation on RHEL, CentOS, and Fedora
For Red Hat Enterprise Linux, Fedora, or AlmaLinux systems, the repository setup uses an rpm script configuration:
curl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.rpm.sh | sudo bash
sudo yum install speedtest
Installation on macOS
Mac users can leverage Homebrew to pull the official binary cleanly without manual repository configurations:
brew install speedtest [--cli]
Once installed, verify the installation by checking the application version:
speedtest --version
Installing the Python Community Variant
If you prefer the pip-based Python script, setup requires python3 and the python package manager. Many Linux distributions also carry it directly in their native repositories.
To install via apt on Debian or Ubuntu systems:
sudo apt install speedtest-cli
Alternatively, install it globally or inside a virtual environment using pip:
sudo pip3 install speedtest-cli
Running the community script relies on calling speedtest-cli directly in your shell, whereas the official binary responds to the speedtest command.
Running Basic Speed Tests and Interpreting Results
Executing a standard test requires no extra flags. Typing the command initiates a handshake, automatically selects a nearby testing server based on latency, and measures download speeds, upload speeds, and packet ping.
speedtest
The output displays your public IP address, the designated test server location, ping metrics, and final throughput metrics measured in megabits per second (Mbps).
When troubleshooting unstable connections, raw numbers aren't always enough. You might want to change how data is displayed. For example, if you prefer seeing data rates in bytes rather than bits, the community script accepts a simple flag:
speedtest-cli --bytes
If you want to skip specific phases of the test to save time—such as omitting the download phase when you only care about upload congestion—you can pass exclusion parameters:
speedtest-cli --no-download
Selecting Custom Servers and Filtering Locations
By default, automated geographic selection works well, but network routing anomalies can sometimes cause the tool to pick a suboptimal node. Pinpointing bottlenecks requires targeting a specific testing host.
To list nearby servers ordered by geographic distance using the community tool:
speedtest-cli --list
The terminal prints a long registry of available servers, each preceded by a unique numeric ID. Locate the server you want to target, copy its ID number, and pass it to the command:
speedtest-cli --server 4321
With the official Ookla CLI, listing servers and selecting them works similarly using server selection flags:
speedtest -L
speedtest -s [server_id]
For automated scripts, specifying a server ID ensures consistent benchmarks over time, removing variations introduced when automated location-matching rotates between different regional hosts.
Automating Diagnostics and Exporting Data in JSON
Command-line utilities shine when integrated into cron jobs, shell scripts, or monitoring pipelines. Instead of reading human-friendly text tables, parsing structured data makes logging bandwidth metrics straightforward.
Both tools support machine-readable output formats. To export results as JSON using the official CLI, specify the format flag:
speedtest -f json
The community script provides a similar JSON flag that suppresses progress bars and outputs clean data structures:
speedtest-cli --json
You can pipe this output directly into data processing tools like jq or append it to a log file to track performance trends over days or weeks:
speedtest --format=json >> speed_log.json
Common Pitfalls and Troubleshooting
Getting unexpected results from your terminal diagnostics usually stems from a few hidden factors. Keeping these common mistakes in mind prevents false conclusions about your Internet service provider:
- Testing over Wi-Fi instead of Ethernet: Wireless interference, channel congestion, and distance from your wireless access point degrade throughput. Always run diagnostic benchmarks on a hardwired Ethernet connection when evaluating your ISP's raw delivery.
- CPU and Memory Bottlenecks: Running bandwidth tests on low-power devices like older single-board computers can max out CPU cores during high-speed transfers, causing artificially low readings because the hardware can't process packets fast enough.
- Ignoring Background Network Traffic: Active downloads, cloud sync applications, or other local devices streaming media on your local area network skew results. Ensure your network is idle before starting a benchmark.
- Mixing Up Binary Packages: Confusing the syntax of the official Ookla binary (
speedtest) with the Python wrapper (speedtest-cli) leads to command-not-found errors or unexpected flag rejections. Check your installed package name if flags fail to execute.
Frequently Asked Questions
Can I run speedtest-cli without root privileges?
Yes. Both the official Ookla binary and the Python community package can be installed and executed entirely within user space without requiring sudo permissions, provided your user account has write access to your local Python site-packages or binary paths.
Why do command-line results differ from browser tests?
Browser tests run inside JavaScript engines which can be affected by browser extensions, hardware acceleration settings, and local tab resource allocation. The command-line tool runs native compiled code or optimized script loops, offering a more direct reading of network socket performance.
How can I schedule regular automated speed tests?
You can combine the JSON export command with a cron schedule on Linux systems. Open your crontab configuration (crontab -e) and add an entry to run the test hourly or daily, saving the output to a dedicated log directory for later analysis.
Does running speedtest-cli consume data caps?
Yes. Every test downloads and uploads real data packets to measure maximum bandwidth limits. Running tests frequently throughout the day on a metered or capped cellular data plan will consume measurable gigabytes of your data allowance.
