networkQuality on Mac: 135 MB a Run, -c Errors Exit 0

I ran networkquality -I nope0 -c, with an interface name that doesn't exist, and nothing happened. It printed nothing and opened no sockets. After 11 minutes and 49 seconds I killed it. A sample of the process showed the main thread parked in semaphore_wait_trap. Adding -M 10, the documented "maximum runtime in seconds," didn't help. That run was still silent at 5 minutes 4 seconds when I killed it too.

That was the worst result from about 20 runs of Apple's built-in network test on my Mac mini. It wasn't the only surprise. A normal run moved 131 to 144 MB through my connection. With -c, a failed test exits 0. The headline RPM number doesn't follow the formula in the IETF draft it cites. And the binary carries an internal help screen with 40 option letters, while the shipped build accepts 17. Below is everything I measured on macOS 26.4.1, with the commands and the numbers.

What networkQuality measures

networkQuality has shipped in /usr/bin since macOS Monterey. Run it with no arguments and it opens parallel HTTP/2 connections to Apple's CDN, saturates the downlink and uplink at the same time, and reports four things: uplink capacity, downlink capacity, idle latency, and "responsiveness" in round-trips per minute (RPM). RPM is 60,000 divided by a latency in milliseconds, measured while the link is loaded. Apple's support page, Test Wi-Fi networks with Apple Network Responsiveness, sorts the result into Low, Medium and High but gives no RPM cut-offs. The draft does: under 300 RPM (200 ms) is poor, 300 to 1,000 fair, 1,000 to 6,000 good, and above 6,000 (under 10 ms) excellent. The method comes from the IETF draft Responsiveness under Working Conditions, now at revision 09 (July 2026).

networkquality            # parallel up+down, ~18 s, human summary
networkquality -v         # same test, per-component latency breakdown
networkquality -s         # upload and download one after the other, ~39 s
networkquality -c         # JSON on stdout
networkquality -u         # download only (-d = upload only)
networkquality -I en0     # bind to one interface

The command works lowercase or as networkQuality, but the man page doesn't. Apple's support page says to run man networkQuality, and that works. man networkquality answers No manual entry for networkquality, because the page is installed as /usr/share/man/man8/networkQuality.8. The page itself is dated September 22, 2020.

One run costs about 135 MB

The man page warns that the tool "will use data on your Internet service plan." It doesn't say how much. I read the interface byte counters (netstat -ib -I en1) before and after each run. My Mac mini is on Wi-Fi, and Apple's config server sent every test to a Seoul edge node (krsel6-edge-fx-00N.aaplimg.com).

Command	Time	Received	Sent	Down / Up (Mbps)	RPM
-c (run 1)	17.8 s	64.3 MB	67.1 MB	27.1 / 45.4	82
-c (run 2)	18.1 s	63.6 MB	72.5 MB	26.5 / 30.4	114
-c (run 3)	19.4 s	67.8 MB	76.0 MB	26.6 / 40.4	79
-v	18.3 s	65.4 MB	68.0 MB	25.9 / 35.7	82
-s (sequential)	38.9 s	62.2 MB	95.6 MB	27.3 / 39.6	155 down, 48 up
-u (download only)	14.8 s	55.0 MB	2.2 MB	27.3 / –	175
-M 5	5.2 s	15.0 MB	18.5 MB	20.1 / 38.7	375
-f h1	19.5 s	69.5 MB	76.4 MB	27.5 / 46.5	182
-f h3	17.2 s	62.7 MB	66.9 MB	26.4 / 75.1	462

A default run used 131 to 144 MB in my tests. The total grows with your connection, because the tool keeps adding flows until throughput stops rising. My link here is about 27 Mbps down, so on a gigabit line expect much more per run. If you're thinking of putting networkQuality in a cron job or a launchd agent every 10 minutes, at my speed that's around 19 GB a day. On a metered or mobile link, run -u or -M instead, or test less often.

Same Mac, same minute: 79 to 462 RPM

The three default runs, a few seconds apart, gave 82, 114 and 79 RPM (all "poor" on the draft's scale, "Low" on Apple's summary), and uplink capacity ranged from 30 to 45 Mbps. Downlink barely moved (26.5 to 27.1). If you compare two runs, the RPM swing alone can be 40%.

Options change the number far more than run-to-run noise does. Forcing HTTP/3 gave 462 RPM, and its uplink jumped to 75 Mbps. Forcing HTTP/1.1 gave 182. -M 5 stopped the test at 5.2 seconds and reported 375, probably because the queue hadn't filled yet (the draft's method keeps loading until latency stabilizes). Those are single runs, so I wouldn't read the HTTP/3 figure as a fact about QUIC. The point is narrower. An RPM number only compares with another one taken with the same flags.

The sequential test shows where my problem is. -s reports download and upload responsiveness separately: 155 RPM while downloading, 48 RPM while uploading. Saturating the upload is what makes latency explode on this Wi-Fi link, which fits the 30% retry rate I measured in home server Wi-Fi vs Ethernet. Idle latency was fine, 5,532 RPM (10.8 ms), so a ping test on Mac would never show it.

The RPM figure isn't the draft's formula

The verbose output prints the parts of the score. From my -v run:

   Responsiveness: Low
      82 RPM (729.563 milliseconds)
         Transport: 458 RPM (130.938 milliseconds)
         Security: 103 RPM (579.046 milliseconds)
         HTTP: 416 RPM (144.015 milliseconds)
         HTTP loaded: 66 RPM (897.471 milliseconds)

Section 5.3.1.1 of the draft averages the three new-connection times (transport, security, HTTP), converts that and the loaded HTTP time to RPM, and takes the mean of the two. With these numbers that gives (210.8 + 66.9) / 2 = 139 RPM. The tool printed 82. I also took the raw arrays from three -c runs and applied the draft's 95% trimmed mean to them. That gave 152, 212 and 173 RPM against reported values of 82, 114 and 79. I tried about a dozen variants (90% trim, medians, only the last quarter of samples) and none matched all three runs. The reported number sits close to the loaded-only value, 60000 divided by the trimmed mean of lud_self_h2_req_resp. Apple doesn't document how the shipped tool weights the parts, so treat the headline as Apple's own aggregate and not a draft-conformant score you can recompute.

With -c, failures exit 0

I tested three kinds of failure. In every one, JSON mode reported the failure in the output and still exited 0:

Failure	Command	Exit code	Output	Time
Cable unplugged (en0 inactive)	-I en0 -c	0	"error_code" : -1009	15 ms
Same, human output	-I en0	1	Error: ... Code=-1009 "The Internet connection appears to be offline." on stdout	<1 s
Unreachable config host	-r 192.0.2.1 -c -M 20	0	"error_code" : -1001 (timed out)	16.1 s
Self-signed local server, no -k	-C https://localhost:4443/config -c	0	"error_code" : -1202	18 ms
Interface name that doesn't exist	-I nope0 -c	none, killed	nothing	11 min 49 s
Same, with a time limit	-I nope0 -M 10 -c	none, killed	nothing	5 min 4 s

A failed JSON run has five or six keys (start_date, end_date, os_version, error_code, error_domain, sometimes test_endpoint), and none of the measurement keys. So a logging script has to check for error_code, not the exit status. Even in human mode, where the exit code is 1, the error text goes to stdout, not stderr. Since nothing bounds the bad-interface hang, wrap the call in an external timeout. macOS has no timeout command by default, which I covered in timeout command not found on Mac.

#!/bin/zsh
# one logged sample; never trust $? from networkquality -c
out=$(gtimeout 60 networkquality -u -c) || { echo "hung or killed" >&2; exit 2; }
if print -r -- "$out" | grep -q '"error_code"'; then
  print -r -- "$out" >> ~/nq-errors.jsonl; exit 1
fi
print -r -- "$out" | tr -d '\n' >> ~/nq.jsonl; echo >> ~/nq.jsonl

Two parsing traps if you keep a history. -c takes an optional filename the old getopt way: -cout.json writes the file, but -c out.json stops with the usage text and exit 1. And the JSON has changed shape between releases. The Ask Different question on the JSON output shows macOS 13.1 writing "end_date" : "12/29/22, 6:27:55 PM" and an integer "responsiveness" : 75. On 26.4.1 I get "2026-10-08 19:31:22.980" and a float. Of the 27 keys in my default output, 10 aren't in the man page, including dl_bytes_transferred, test_endpoint and an other object that counts which protocol, ECN and interface type each probe used.

Testing your own LAN with -S

Every test above measures the path to Apple's CDN, so it mixes your Wi-Fi with your ISP. For the LAN alone, one Mac can be the server. networkquality -S 4443 starts a server, and the man page says it "will display the URL of the config-file." With stdout redirected to a file it printed nothing at all. The config was at /config and /.well-known/nq:

$ networkquality -S 4443 &
$ curl -sk https://localhost:4443/config
{ "urls" : {
    "large_download_url" : "https://Mindfului-Macmini.local:4443/large",
    "small_download_url" : "https://Mindfului-Macmini.local:4443/small",
    "upload_url" : "https://Mindfului-Macmini.local:4443/slurp" }, "version" : 1 }
$ networkquality -C https://localhost:4443/config -k -c

Two things to know before you leave it running. It listens on *:4443, every interface, not just loopback. And it advertises itself over Bonjour as _nq._tcp under the computer's name, which networkquality -b lists from any Mac on the network. You also have to pass -k, because the certificate is self-signed. Without it the client fails in 18 ms with error -1202 and exits 0. Against itself over lo0 my Mac mini reported 8.84 Gbps down, 3.79 Gbps up and 3,182 RPM, and downloaded 16.5 GB in 15 seconds. That's the ceiling of the test machinery, not of any network. Run the client on a second Mac to measure the link between them. Apple's reference servers and setup notes are in network-quality/server on GitHub.

The hidden options

The binary is 322,448 bytes and holds two option strings. The one in use, B:bC:c::dF:f:hI:kM:pr:S:suv, has 17 letters. The other has 40, and a second, internal help screen describes most of the 23 extra letters: -A for CSV output, -L and -l for download and upload data limits in MB, -x for repeated runs, -N for continuous mode, -i to skip idle latency, and a usage line that starts with -4. I tried five of them (-A, -L, -x, -N, -i) and each one stopped with invalid option and exit 1. So the data cap you'd want for a metered link exists in the code and is switched off in the build Apple ships. In a 2021 Hacker News thread, one commenter wished the tool had a -4/-6 option for an IPv6-only problem. The internal usage line has -4, and the public build rejects it.

The public help is slightly off too. -F (flow-count limits) is accepted but appears in neither the help list nor the usage line. -M is in the help list but not in the usage line.

What other people report

The two big Hacker News threads, "macOS Monterey's new network quality tool is surprisingly good" (2021, 468 points, 95 comments) and "The networkQuality tool on macOS" (2023, 397 points, 84 comments), raise the same doubts I hit. One commenter in France said Apple's CDN didn't reliably max out a 400 MB/s line. Another found the uplink consistently read about a sixth of what they could reach otherwise. A user in Norway said responsiveness differed greatly between tests, which fits my 79 to 114 spread. And a satellite user got a crash with NSInvalidArgumentException on the first release. My numbers come from one Mac in Seoul on Wi-Fi, so they say nothing about how Apple's CDN performs elsewhere. They do confirm that a single run is a weak basis for a comparison.

Like textutil reporting failed reads as success and traceroute waiting 15 seconds per silent hop, networkQuality behaves best in front of a person watching the terminal. For a script, check the output, put a timeout around it, and budget the data.

FAQ

How much data does networkQuality use?

In my tests on a roughly 27 Mbps down, 40 Mbps up Wi-Fi connection, a default networkQuality run moved 131 to 144 MB in about 18 seconds, split about evenly between download and upload. The sequential mode (-s) used 158 MB and took 39 seconds. The amount scales with connection speed, so a faster line uses more per run. Use -u for a download-only test or -M to cap the runtime.

What is a good RPM in networkQuality?

Apple sorts responsiveness into Low, Medium and High but doesn't publish the RPM boundaries. The IETF draft behind the tool sets four bands: under 300 RPM is poor, 300 to 1,000 fair, 1,000 to 6,000 good, and above 6,000 RPM (under 10 ms of latency under load) excellent. My Wi-Fi Mac mini scored 79 to 114, poor by that scale. RPM varies a lot between runs and with options like -s, -f h3 or -M, so compare only runs taken with the same flags.

Why does networkQuality -c return exit code 0 when the test fails?

In JSON mode on macOS 26.4.1, networkQuality reports errors as error_code and error_domain fields in the JSON and still exits 0. This happened for an offline interface (-1009), an unreachable server (-1001) and an untrusted certificate (-1202). Check the output for an error_code key. In human mode the same failures exit 1. An interface name that doesn't exist makes it hang with no output, even with -M, so wrap it in an external timeout.

Method: all runs were on 2026-10-08 between 19:31 and 19:52 KST on a Mac mini M4 (Mac16,10, macOS 26.4.1 build 25E253) connected over Wi-Fi (en1; the Ethernet port en0 was unplugged), using /usr/bin/networkquality (322,448 bytes, man page dated 2020-09-22). Data per run is the change in netstat -ib byte counters on en1 across the run, so it includes any other traffic on the Mac during those seconds. Every option other than the default was run once. The RPM recomputation applied section 5.3.1.1 of draft-ietf-ippm-responsiveness-09 to the verbose components and to the JSON sample arrays. The hidden option list comes from strings on the binary. I tested 5 of the 23 extra letters, not all of them. The hang cases were killed by hand at the times shown. They didn't exit on their own. Community reports are from the two Hacker News threads linked above, read through the Algolia API.