~/ linuxnetwork.net

speedtest-cli: Test Internet Bandwidth Using speedtest.net via Command Line

Whether you’re a system administrator monitoring server connectivity, a developer troubleshooting slow APIs, or a casual user verifying your ISP’s promised bandwidth, speedtest-cli is an indispensable tool. It’s a free, open-source Python script that brings the functionality of speedtest.net to the command line, enabling you to measure download/upload speeds and latency without a graphical interface.

Unlike the web-based speedtest.net, speedtest-cli works on headless servers, embedded systems, and any environment with Python support. It uses the same global network of speedtest.net servers, ensuring consistent, reliable results that align with the web version. This guide will walk you through installation, usage, advanced features, best practices, and troubleshooting to help you get the most out of speedtest-cli.

Table of Contents#

  1. Prerequisites
  2. Installation Methods
  3. Basic Usage & Core Commands
  4. Advanced Features
  5. Common Use Cases
  6. Best Practices for Accurate Results
  7. Troubleshooting Common Issues
  8. Alternatives to speedtest-cli
  9. References

Prerequisites#

Before installing speedtest-cli, ensure your system meets these requirements:

  • Python 3.6+: Newer versions of speedtest-cli require Python 3.6 or higher. Check your Python version with: 
    python3 --version
  • Pip (Optional): Required for installing speedtest-cli via Python’s package manager. Most modern systems include pip by default, but you can install it if missing (e.g., apt install python3-pip on Debian/Ubuntu).

Installation Methods#

speedtest-cli can be installed via multiple methods, depending on your operating system.

1. Using Pip (Cross-Platform)#

The simplest way to install speedtest-cli globally is with pip:

# Install for all users (requires sudo)
sudo pip install speedtest-cli
 
# Install for your user only (avoids sudo)
pip install --user speedtest-cli

If you use --user, add your local pip bin directory to your PATH (e.g., export PATH="$HOME/.local/bin:$PATH" for Linux/macOS).

2. System Package Managers#

For Debian/Ubuntu-based systems:

sudo apt update && sudo apt install speedtest-cli

For RHEL/CentOS/Rocky Linux:

# RHEL 8+/CentOS 8+
sudo dnf install speedtest-cli
 
# Older RHEL/CentOS versions
sudo yum install speedtest-cli

For macOS (using Homebrew):

brew install speedtest-cli

3. Manual Download (Latest Version)#

If you want the most up-to-date version (often newer than package manager releases):

# Download the script from GitHub
curl -L https://raw.githubusercontent.com/sivel/speedtest-cli/master/speedtest.py > speedtest-cli
 
# Make it executable
chmod +x speedtest-cli
 
# Move to a system-wide bin directory (optional)
sudo mv speedtest-cli /usr/local/bin/

Basic Usage & Core Commands#

Start with these fundamental commands to get familiar with speedtest-cli.

1. Run a Basic Speed Test#

The simplest command automatically selects the closest server (by latency) and runs a full download/upload test:

speedtest-cli

Sample output:

Retrieving speedtest.net configuration...
Testing from Example ISP (192.168.1.100)...
Retrieving speedtest.net server list...
Selecting best server based on ping...
Hosted by Example Server (City, State) [10.23 km]: 12.345 ms
Testing download speed........................................
Download: 98.76 Mbit/s
Testing upload speed..........................................
Upload: 45.67 Mbit/s

2. List Available Servers#

To see all nearby speedtest.net servers (sorted by distance):

speedtest-cli --list

Output includes server IDs, names, locations, and distances. Example:

1234) Example Server (New York, NY, US) [5.67 km]
5678) Another ISP (Jersey City, NJ, US) [12.34 km]

3. Specify a Server#

Test against a specific server using its ID (from the --list command):

speedtest-cli --server 1234

4. Share Results#

Generate a public URL to share your results (matches the web version’s result page):

speedtest-cli --share

Sample output includes a link like:

Share results: https://www.speedtest.net/result/c/1234567890

5. Structured Output (CSV/JSON)#

For automated logging or programmatic use, output results in CSV or JSON format:

  • CSV:

    speedtest-cli --csv
# Append to a log file for monitoring
speedtest-cli --csv >> bandwidth_log.csv

    CSV columns: server_id,server_name,server_location,server_country,server_sponsor,server_distance,server_ping,download,upload,share_url,timestamp

  • JSON:

    speedtest-cli --json
# Save to file
speedtest-cli --json > speedtest_results.json

    JSON output includes detailed fields like latency, bytes sent/received, and server metadata.

Advanced Features#

Unlock more functionality with these advanced flags:

1. Quiet Mode#

Suppress all extra output and only display the core results (download, upload, ping):

speedtest-cli --quiet

Output: 98.76 Mbit/s,45.67 Mbit/s,12.345 ms

2. Show Results in Bytes#

By default, speedtest-cli uses bits per second (standard for internet bandwidth). To switch to bytes per second:

speedtest-cli --bytes

3. Skip Download/Upload Tests#

Test only upload or download speed by skipping the other:

# Skip download test
speedtest-cli --no-download
 
# Skip upload test
speedtest-cli --no-upload

4. Exclude Servers#

Avoid testing against specific servers (useful if a server is unreliable):

speedtest-cli --exclude 5678 9012

5. Proxy Support#

Test bandwidth through an HTTP/HTTPS proxy:

speedtest-cli --proxy http://user:[email protected]:8080

6. Exclude IPv6 Servers#

If your network has IPv6 issues, force speedtest-cli to use IPv4 only:

speedtest-cli --ipv4

Common Use Cases#

speedtest-cli shines in scenarios where GUI tools aren’t feasible or automation is required.

1. Automated Bandwidth Monitoring#

Set up a cron job to run daily tests and log results for trend analysis:

# Open crontab editor
crontab -e
 
# Add this line to run at 2 AM daily (non-peak hours)
0 2 * * * /usr/bin/speedtest-cli --csv >> /var/log/bandwidth/daily_log.csv

You can visualize logs with tools like Grafana or Excel to track ISP performance over time.

2. Server Benchmarking#

Compare connectivity to multiple servers to find the most reliable route for your applications:

# Test 3 servers and save results to a file
for id in 1234 5678 9012; do
  speedtest-cli --server $id --csv >> server_benchmarks.csv
done

3. Troubleshooting Connectivity#

Verify if slow application performance is due to bandwidth issues or server-side problems. Run speedtest-cli before and after making network changes (e.g., upgrading a router) to measure improvements.

Best Practices for Accurate Results#

To ensure your speed test results are reliable, follow these guidelines:

  1. Close Background Processes: Pause downloads, uploads, video calls, and other bandwidth-heavy tasks.
  2. Use a Wired Connection: Wi-Fi is prone to interference—switch to Ethernet for consistent results.
  3. Test Multiple Times: Results can vary due to network congestion; run 3-5 tests and average them.
  4. Avoid Peak Hours: ISP networks are busiest between 7 PM–11 PM local time—test during off-peak hours for better accuracy.
  5. Test Nearest Servers: While speedtest-cli selects the closest server by default, testing 2-3 nearby servers helps identify outliers.
  6. Disable VPN/Proxy: Unless you’re testing through a proxy, turn off VPNs as they can add latency and throttle speeds.

Troubleshooting Common Issues#

1. Installation Errors#

  • Pip Not Found: Install pip with apt install python3-pip (Debian) or brew install python3 (macOS).
  • Permission Denied: Use pip install --user speedtest-cli instead of sudo to avoid system-wide permission issues.

2. Connection Timeouts#

  • Firewall Blocking Traffic: Ensure outbound connections to port 80/443 are allowed for speedtest.net servers.
  • DNS Issues: Test with nslookup speedtest.net—if it fails, update your DNS servers (e.g., use 8.8.8.8 for Google DNS).

3. Inaccurate Results#

  • Background Traffic: Use htop (Linux) or Activity Monitor (macOS) to identify and kill bandwidth-heavy processes.
  • Overloaded Servers: Switch to a different server using --server <id> if the default server is slow.

4. "Command Not Found" After Installation#

  • Add your local pip bin directory to PATH: export PATH="$HOME/.local/bin:$PATH" (Linux/macOS) and save it to ~/.bashrc or ~/.zshrc.

Alternatives to speedtest-cli#

While speedtest-cli is the most popular option, consider these alternatives:

  1. fast-cli: A lightweight tool from Netflix that tests download speed quickly (no upload test): 
    npm install -g fast-cli
fast-cli
  2. iperf3: Tests bandwidth between two endpoints (ideal for local network or private server benchmarking): 
    # On server: iperf3 -s
# On client: iperf3 -c <server-ip>
  3. speedtest-go: A cross-platform binary written in Go (no Python required) with similar features to speedtest-cli.

References#

2026-03