Introduction
When you experience slow internet speeds, buffering video, or lag during video calls on your Mac, the standard response is to run a web-based speed test. However, web-based tests often rely on third-party servers heavily laden with JavaScript and ads, providing inconsistent results. Starting with macOS Monterey, Apple included a powerful, native command-line tool called networkquality that tests your connection’s true throughput and responsiveness directly from the Terminal. This guide explains how to use it.
What is `networkquality`?
The networkquality tool contacts Apple’s Content Delivery Network (CDN) servers to measure your upload speed, download speed, and “Responsiveness.” Responsiveness is Apple’s term for measuring Bufferbloat (Round-Trip Time or RTT) under working conditions. It determines how quickly your network responds when it is simultaneously downloading and uploading heavy loads, which is crucial for applications like FaceTime and Zoom.
Step 1: Open the Terminal
Navigate to Applications > Utilities and launch Terminal, or press Cmd + Space, type Terminal, and press Enter.
Step 2: Run a Basic Test
To run the standard network quality test, simply type the following command and press Enter:
networkquality
The test will run for approximately 15 to 20 seconds. By default, it runs upload and download tests in parallel, simulating a real-world scenario like a video conference where you are sending and receiving data simultaneously.
The output will display:
- Upload capacity: Your speed in Megabits per second (Mbps).
- Download capacity: Your speed in Mbps.
- Upload/Download flows: The number of concurrent connections used.
- Responsiveness: Categorized as Low, Medium, or High (High is the best).
Step 3: Run Sequential Tests
Web-based speed tests (like Ookla) typically run tests sequentially—download first, then upload. If you want to compare Apple’s tool against a web test, you must force networkquality to test sequentially. Use the -s flag:
networkquality -s
You will often notice that sequential download speeds are slightly higher than parallel speeds, but parallel testing provides a more realistic picture of network stress.
Step 4: Output the Results to JSON
If you are an administrator automating network diagnostics across a fleet of Macs, you can force the tool to output its final results in a structured JSON format. This allows scripts to easily parse the speeds and latency metrics. Use the -c flag:
networkquality -c
The tool will run silently and then dump a JSON dictionary to standard output containing detailed metadata, including the exact server queried, connection types, and granular latency measurements.