Skip to content

FAQ & Troubleshooting

Common questions and solutions for speedtest-cli.

General Questions

What is speedtest-cli?

speedtest-cli is a command-line tool for testing your internet connection speed. It uses Cloudflare's global network infrastructure to measure download/upload speeds, latency, jitter, and other network metrics.

How accurate is speedtest-cli?

speedtest-cli provides accurate measurements when:

  • You're connected via Ethernet (Wi-Fi adds variability)
  • No other applications are using bandwidth
  • Tests are run to nearby Cloudflare servers
  • Adequate test file sizes are used

Results may vary slightly from other speed test tools due to different testing methodologies and server locations.

Which servers does speedtest-cli use?

speedtest-cli uses Cloudflare's global network (speed.cloudflare.com). It automatically connects to the nearest Cloudflare edge server for optimal performance.

Can I choose a specific server?

Currently, speedtest-cli automatically selects the nearest Cloudflare server. Manual server selection is not supported, but it's on the roadmap for future releases.

Is my data private?

Yes. speedtest-cli:

  • ✅ Uses HTTPS for all connections
  • ✅ Doesn't collect personal information
  • ✅ Doesn't store browsing history
  • ✅ Is open source (auditable)
  • ✅ Doesn't send telemetry to developers

The only data transmitted is: - Test data to/from Cloudflare - Your IP address (necessary for routing)

Is speedtest-cli free?

Yes, speedtest-cli is completely free and open source under the MIT License.

Does it work offline?

No, speedtest-cli requires an active internet connection to test your speed.

Installation Issues

Command Not Found After Installation

Problem: speedtest-cli: command not found

Solutions:

  1. Ensure installation path is in PATH:

```bash # For pipx pipx ensurepath

# Restart terminal or reload shell source ~/.bashrc # or ~/.zshrc ```

  1. Verify installation:

bash pipx list # or uv tool list

  1. Reinstall:

bash pipx uninstall speedtest-cloudflare-cli pipx install speedtest-cloudflare-cli

  1. Use full path:

bash ~/.local/bin/speedtest-cli

Permission Denied During Installation

Problem: Permission errors with pip

Solutions:

  1. Use pipx or uv instead (recommended):

bash pipx install speedtest-cloudflare-cli

  1. Install for current user only:

bash pip install --user speedtest-cloudflare-cli

  1. Don't use sudo with pip (can break system packages)

Python Version Incompatibility

Problem: Requires Python 3.9+

Solutions:

  1. Check Python version:

bash python --version

  1. Install compatible Python:

```bash # Ubuntu/Debian sudo apt install python3.12

# macOS brew install python@3.12 ```

  1. Use pyenv for multiple Python versions:

bash pyenv install 3.12 pyenv global 3.12

Package Not Found on PyPI

Problem: Could not find a version that satisfies the requirement

Solution:

Ensure correct package name:

# ✅ Correct
pip install speedtest-cloudflare-cli

# ❌ Wrong
pip install speedtest-cli  # Different package!

Usage Issues

Tests Are Very Slow

Problem: Speed tests take too long to complete

Possible Causes & Solutions:

  1. Large test files on slow connection:

bash # Use smaller file sizes speedtest-cli -ds 10 -us 5

  1. Network congestion:
  2. Test during off-peak hours

  3. Close bandwidth-heavy applications

  4. Wi-Fi interference:

  5. Switch to Ethernet
  6. Move closer to router

  7. Test on 5GHz band if available

  8. System resources:

  9. Close unnecessary applications
  10. Check CPU/memory usage

Ping/Latency Test Fails

Problem: Ping test failed or very high latency

Solutions:

  1. ICMP may be blocked:

speedtest-cli automatically falls back to HTTP latency measurement. This is normal and expected in many environments.

  1. Grant ICMP permissions (Linux):

bash # Not recommended for security reasons sudo setcap cap_net_raw+ep $(which python3)

  1. Use HTTP latency instead:

HTTP latency is displayed automatically and is sufficient for most use cases.

  1. Check firewall:
  2. Ensure outbound HTTPS is allowed
  3. Check for corporate firewall rules

Connection Timeout Errors

Problem: Connection timeout or Network unreachable

Solutions:

  1. Check internet connection:

bash ping 1.1.1.1 curl https://speed.cloudflare.com

  1. Check proxy settings:

speedtest-cli respects system proxy settings. Ensure they're correct.

  1. Disable VPN temporarily:

Some VPNs may interfere with speed tests.

  1. Check firewall:

Allow outbound HTTPS connections to *.cloudflare.com

  1. Try different network:

Test on different Wi-Fi or Ethernet connection.

Results Differ from Other Speed Tests

Problem: Different results compared to Ookla, Fast.com, etc.

Explanation:

This is normal and expected because:

  • Different servers: speedtest-cli uses Cloudflare, others use different networks
  • Different methodologies: Varying test algorithms
  • Different times: Network conditions change
  • Different locations: Server distances vary

Tips for Consistency:

  1. Run multiple tests:

bash speedtest-cli --attempts 5

  1. Test at same time of day
  2. Use same connection type (Wi-Fi vs Ethernet)
  3. Close background applications

Web Dashboard Won't Open

Problem: --web_view doesn't open browser

Solutions:

  1. Manually open HTML file:

```bash # Linux/macOS find /tmp -name "speedtest_dashboard*.html" -exec firefox {} \;

# macOS open "$(find /tmp -name 'speedtest_dashboard*.html' | head -1)" ```

  1. Check default browser:

Ensure you have a default browser configured.

  1. Permissions:

Check that /tmp is writable:

bash ls -ld /tmp

  1. Try different browser:

bash # Specify browser BROWSER=chromium speedtest-cli --web_view

JSON Output Not Working

Problem: --json produces no output or errors

Solutions:

  1. Check for syntax errors:

bash speedtest-cli --json | jq .

  1. Redirect errors:

bash speedtest-cli --json 2>&1 | tee output.log

  1. Check file permissions:

bash speedtest-cli --json-output results.json ls -l results.json

Performance Issues

Slower Speeds Than Expected

Problem: Test results slower than ISP advertised speeds

Troubleshooting Steps:

  1. Use Ethernet connection:

Wi-Fi typically slower than wired.

  1. Test at different times:

Network congestion varies throughout day.

  1. Close bandwidth-heavy apps:
  2. Stop downloads/uploads
  3. Pause cloud sync (Dropbox, Google Drive)
  4. Close streaming services

  5. Disable auto-updates

  6. Restart router/modem:

Power cycle your network equipment.

  1. Check for ISP issues:

Contact ISP if consistently slow.

  1. Test on different devices:

Isolate whether issue is device-specific.

  1. Check system resources:

bash top # or htop

  1. Disable QoS:

Quality of Service settings may limit speed.

High Jitter Values

Problem: Jitter is high (> 30ms)

Causes & Solutions:

  1. Wi-Fi interference:
  2. Switch to Ethernet
  3. Change Wi-Fi channel

  4. Move closer to router

  5. Network congestion:

  6. Test during off-peak hours

  7. Close bandwidth-heavy applications

  8. ISP issues:

  9. Contact ISP if persistent

  10. Check for service outages

  11. Router issues:

  12. Restart router
  13. Update router firmware
  14. Replace old router

High Ping Latency

Problem: Ping is high (> 100ms)

Possible Causes:

  1. Geographic distance to server:
  2. Normal if far from Cloudflare edge

  3. Check with metadata.colo

  4. Network routing:

  5. ISP routing inefficiency

  6. Use traceroute to diagnose

  7. VPN/Proxy:

  8. Adds latency

  9. Test without VPN

  10. Wi-Fi:

  11. Switch to Ethernet
  12. Reduce interference

Docker/Container Issues

Cannot Pull Docker Image

Problem: Error response from daemon: pull access denied

Solutions:

  1. Use correct image name:

bash docker pull ghcr.io/takitsu21/speedtest:latest

  1. Check network connectivity:

bash ping ghcr.io

  1. Retry pull:

bash docker pull --quiet ghcr.io/takitsu21/speedtest:latest

Container Doesn't Show Output

Problem: Docker container runs but no output

Solutions:

  1. Use -it flags:

bash docker run --rm -it ghcr.io/takitsu21/speedtest:latest

  1. Check logs:

bash docker logs <container-id>

  1. Run with shell:

bash docker run --rm -it ghcr.io/takitsu21/speedtest:latest sh speedtest-cli

Docker Permission Denied (Linux)

Problem: permission denied while trying to connect to Docker daemon

Solutions:

  1. Add user to docker group:

bash sudo usermod -aG docker $USER newgrp docker

  1. Use Podman (rootless):

bash podman run --rm -it ghcr.io/takitsu21/speedtest:latest

  1. Use sudo (not recommended):

bash sudo docker run --rm -it ghcr.io/takitsu21/speedtest:latest

API/Library Usage Issues

Import Errors

Problem: ModuleNotFoundError: No module named 'speedtest_cloudflare_cli'

Solutions:

  1. Verify installation:

bash pip list | grep speedtest

  1. Install package:

bash pip install speedtest-cloudflare-cli

  1. Check Python path:

python import sys print(sys.path)

  1. Use virtual environment:

bash python -m venv venv source venv/bin/activate pip install speedtest-cloudflare-cli

Type Checking Errors

Problem: mypy shows type errors

Solution:

Install type stubs if needed:

pip install types-httpx

The library includes type hints, so most IDEs will have proper autocomplete.

Platform-Specific Issues

Windows Issues

Problem: Various Windows-specific issues

Solutions:

  1. Use Windows Terminal:

Download from Microsoft Store for best experience.

  1. PowerShell encoding:

powershell [Console]::OutputEncoding = [System.Text.Encoding]::UTF8

  1. Path issues:

Add Python Scripts directory to PATH: C:\Users\YourName\AppData\Local\Programs\Python\Python312\Scripts

  1. ICMP permissions:

Usually available by default on Windows.

macOS Issues

Problem: macOS-specific issues

Solutions:

  1. System Integrity Protection:

No special configuration needed.

  1. Homebrew Python:

Use pipx or uv to avoid conflicts.

  1. Terminal permissions:

Grant Terminal full disk access in System Preferences if needed.

Linux Issues

Problem: Linux-specific issues

Solutions:

  1. ICMP permissions:

bash # Grant capabilities (optional) sudo setcap cap_net_raw+ep $(which python3)

  1. Snap/Flatpak isolation:

Use native installation instead.

  1. SELinux:

May need to adjust policies in rare cases.

Comparing with Other Tools

vs. Ookla Speedtest

Differences:

  • Backend: Cloudflare vs Ookla servers
  • Open Source: Yes vs No
  • CLI-first: Yes vs GUI-first
  • Privacy: High vs Medium

When to use speedtest-cli: - Command-line workflows - Automation/scripting - Privacy concerns - Cloudflare infrastructure testing

When to use Ookla: - Need server selection - Prefer GUI - ISP uses Ookla for official tests

vs. Fast.com

Differences:

  • Backend: Cloudflare vs Netflix CDN
  • CLI: Native vs Web-only
  • Metrics: Comprehensive vs Basic
  • Automation: Easy vs Difficult

When to use speedtest-cli: - More detailed metrics needed - CLI automation required - JSON output needed

When to use Fast.com: - Quick browser test - Netflix streaming quality

Getting More Help

Check Documentation

Report Issues

If you've found a bug:

  1. Check existing issues
  2. Create a new issue with:
  3. OS and Python version
  4. speedtest-cli version
  5. Steps to reproduce
  6. Error messages
  7. Expected vs actual behavior

Ask Questions

Enable Debug Output

For troubleshooting, run with verbose Python logging:

python -m speedtest_cloudflare_cli.main --help

Common Error Messages

"Network error: Could not connect to speed.cloudflare.com"

Cause: Cannot reach Cloudflare servers

Solution: 1. Check internet connection 2. Check firewall settings 3. Try with VPN disabled 4. Verify DNS resolution: nslookup speed.cloudflare.com

"Permission denied: Cannot create file"

Cause: No write permissions for output file

Solution:

# Check permissions
ls -la /path/to/output/

# Use writable location
speedtest-cli --json-output ~/results.json

"ModuleNotFoundError"

Cause: Package not installed or wrong environment

Solution:

# Verify installation
pip show speedtest-cloudflare-cli

# Reinstall
pip install --force-reinstall speedtest-cloudflare-cli

"Command 'speedtest-cli' not found"

Cause: Installation path not in PATH

Solution: See Command Not Found above.

Tips for Best Results

Optimize Test Accuracy

  1. Use Ethernet instead of Wi-Fi
  2. Close all applications using bandwidth
  3. Run multiple tests with --attempts 3
  4. Test at different times to see variance
  5. Restart router before important tests

Automation Best Practices

  1. Use silent mode in scripts
  2. Export to JSON for parsing
  3. Don't test too frequently (respect bandwidth)
  4. Handle errors gracefully in scripts
  5. Log results for historical tracking

Performance Tuning

  1. Adjust test sizes based on connection speed
  2. Use download-only for quick tests
  3. Enable silent mode to reduce overhead
  4. Run from containers for isolation

Still have questions? Open a discussion on GitHub!