Speedtest CLI for Python

Common errors

• ERROR: Unable to connect to servers to test latency.

  cause This usually indicates a temporary network connectivity issue, a firewall blocking outgoing connections, or occasionally, a server-side issue. Some users report this error more frequently when running automated tests at specific times (e.g., on the half-hour), possibly due to perceived rate-limiting or a bug in server selection.
  fix Verify your internet connection and firewall settings. Try running the test again later or at a different time. If persistent, check for broader network issues or server availability.

• AttributeError: partially initialized module 'speedtest' has no attribute 'Speedtest' (most likely due to a circular import). Did you mean: 'speedtest'?

  cause You likely named your Python script `speedtest.py`. When your script tries to `import speedtest`, Python loads your script instead of the installed `speedtest-cli` library, causing a circular import and this error.
  fix Rename your Python script to something other than `speedtest.py` (e.g., `my_speedtest.py`) to avoid shadowing the installed package.

• [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:XXXX)

  cause This error points to an issue with SSL certificate validation. It can be caused by outdated root certificates on your system, an issue with Python's access to the certificate store, or network proxies performing SSL interception.
  fix Ensure `certifi` is up-to-date (`pip install --upgrade certifi`). On macOS, run `/Applications/Python \ 3.x/Install \ Certificates.command`. Verify your system's certificate store is current. If behind a corporate proxy, check if it's interfering with SSL.

• command not found: speedtest

  cause After installing `speedtest-cli` with `pip`, the executable script might be placed in a directory not included in your system's `PATH` environment variable. Common on Linux/macOS for `~/.local/bin` not being in PATH.
  fix Add the directory where `pip` installs user scripts (e.g., `~/.local/bin` on Linux/macOS, or the `Scripts` subdirectory of your Python installation on Windows) to your system's `PATH`. Remember to restart your terminal or command prompt.

Warnings

• breaking The Python API was redesigned in version 2.0.0, and the `speedtest_cli.py` script was removed. Code directly importing or executing `speedtest_cli.py` will no longer work.
  Fix: Update your code to use the `speedtest` module and its `Speedtest` class (e.g., `import speedtest; st = speedtest.Speedtest()`).
• gotcha Inconsistent results may occur compared to the official Speedtest.net website or Ookla's native CLI. This is often due to differences in testing protocols (HTTP vs. raw sockets) and Python's performance characteristics on various systems.
  Fix: Understand that `speedtest-cli` is an open-source implementation and inherent inconsistencies are acknowledged by the developers. It's best used for relative measurements or when a programmatic solution is required, rather than for absolute official benchmarks.
• gotcha SSL Certificate Verification Failures (`CERTIFICATE_VERIFY_FAILED`) can block tests. This is typically due to outdated system certificates, Python's certificate store issues, or network intermediaries like corporate proxies performing SSL inspection.
  Fix: Update `certifi` (`pip install --upgrade certifi`). Ensure your system's root certificates are up-to-date. If behind a corporate network, consult IT regarding SSL inspection. Using `--secure` with the CLI might help in some cases but is not a universal fix.
• gotcha Proxy support can be inconsistent. While `speedtest-cli` generally respects `http_proxy` and `https_proxy` environment variables, some internal functionalities (like sharing results via `--share`) might not fully route through the configured proxy in all environments or versions.
  Fix: Ensure `http_proxy` and `https_proxy` environment variables are correctly set. Test thoroughly if proxying is critical for all operations. Version 2.1.2 included proxy support fixes.
• gotcha Some Python 3.8+ users might experience warnings or minor issues due to older compatibility patterns. Version 2.1.2 specifically addressed warnings on Python 3.8.
  Fix: Ensure you are running `speedtest-cli` version 2.1.2 or newer to prevent warnings on Python 3.8 and later.

Install

• pip install speedtest-cli Install via pip

Imports

• Speedtest
  wrong:

  import speedtest_cli

  correct:

  import speedtest
  st = speedtest.Speedtest()

  The primary programmatic interface is the `speedtest` module and its `Speedtest` class. Direct import or execution of `speedtest_cli.py` was deprecated and removed in version 2.0.0.

Quickstart

This quickstart demonstrates how to import the `speedtest` module, initialize the `Speedtest` object, find the best server, and then measure download and upload speeds programmatically. The speeds are converted to a human-readable format for clarity.

import speedtest
import os

def human_readable_bytes(nbytes):
    suffixes = ['B', 'KB', 'MB', 'GB', 'TB', 'PB']
    i = 0
    while nbytes >= 1024 and i < len(suffixes)-1:
        nbytes /= 1024
        i += 1
    f = ('%.2f' % nbytes).rstrip('0').rstrip('.')
    return '%s %s' % (f, suffixes[i])

print('Starting Speedtest...')
st = speedtest.Speedtest()

# Find best server based on ping
print('Finding best server...')
st.get_best_server()
print(f'Hosted by {st.results.server['sponsor']} ({st.results.server['name']}) [Ping: {st.results.ping:.2f} ms]')

# Test download speed
print('Testing download speed...')
download_speed_bps = st.download()
download_speed_mbps = download_speed_bps / 1_000_000 # Convert to Mbps
print(f'Download: {human_readable_bytes(download_speed_bps)} ({download_speed_mbps:.2f} Mbps)')

# Test upload speed
print('Testing upload speed...')
upload_speed_bps = st.upload()
upload_speed_mbps = upload_speed_bps / 1_000_000 # Convert to Mbps
print(f'Upload: {human_readable_bytes(upload_speed_bps)} ({upload_speed_mbps:.2f} Mbps)')

# Get full results (optional)
# results = st.results.dict()
# print(results)