Scans and scopes

Scan the startup drive

census, census scan and census scan --scope drive all do the same thing: scan the whole startup drive and save the result.

census scan

A drive scan covers the System volume, the Data volume that holds your files and apps, and the startup drive’s support volumes (Preboot, VM, Update). It stops at every other mount: external drives, network shares and mounted disk images.

A scan never follows symbolic links, never reads what is inside your files, and never changes anything. It records names, sizes and dates.

Choose a scope

Every command that reads a scan takes a scope. Use the same scope for every step of a job, so findings, clean and review all look at the same scan.

# Scan only your Downloads folder
census scan --path ~/Downloads

# Scan an external drive: give its mount point as the path
census scan --path /Volumes/Backup

# Query that folder's scan, not the drive's
census top --path ~/Downloads

The apps commands (apps, app, leftovers and uninstall) need a scan that includes /Applications and ~/Library, which the default drive scan does.

Read the summary

Without --json, a scan prints a short summary:

Macintosh HD   225 GB used · 20.0 GB free

  90.4 GB   █████▋          Other users
  49.0 GB   ███             App data
  35.0 GB   ██▏             macOS
  18.7 GB   █▏              Hidden space
  …

Biggest files
  47.3 GB   ~/Library/Containers/…/2B5D7503.img

Safe to clean: 1.3 GB → census findings

• Used and free match diskutil and Disk Utility.
• The rows add up to the used space. Every size is space on disk, not the files’ nominal length.
• Hidden space is used space census can’t see as files: snapshots, the Recovery volume, files macOS protects, and folders it couldn’t read.

census report shows the details behind the numbers, and census scan --verbose prints the scan’s diagnostics before the summary.

Why Finder shows less used space

Finder counts purgeable space (snapshots, iCloud files it can download again, some caches) as free. census counts it as used until macOS actually frees it. In JSON, coverage_details.capacity.purgeable_bytes is that amount, when macOS reports it.

Saved scans and rescans

Each scan saves its folder tree in ~/Library/Caches/census/, one file per scope, and keeps a JSON report of it in ~/Library/Application Support/census/history/, the 20 newest. Set CENSUS_CACHE_DIR or CENSUS_DATA_DIR to move them. --no-save scans without saving either.

The next scan of the same scope is incremental: it replays macOS’s file system event log since the saved scan, reads again only the folders that changed, and merges them into the saved tree. It falls back to a full scan, and reports why, when:

• there is no saved scan yet, or macOS was updated;
• Full Disk Access or the user changed;
• a volume was replaced, or its event history was reset;
• the event log dropped events or too many folders changed;
• the last full scan is more than 7 days old, or 50 rescans have run since it.

--full forces a full scan. In JSON, scan_mode is full or incremental, and full_scan_reason says why a full scan ran despite a saved one.

Query a saved scan

Queries such as top, ls, findings and duplicates read the newest saved scan of their scope. They don’t walk the disk again, so the answer is as fresh as that scan. Add --refresh to rescan the scope first:

# Answer from the saved scan
census findings

# Rescan first, then answer
census findings --refresh

Without a scope, census ls PATH and census top --under PATH use the newest saved scan that contains PATH. census scans lists every saved scan:

census scans --json

{
  "schema_version": 5,
  "command": "scans",
  "status": "ok",
  "exit_code": 0,
  "errors": [],
  "warnings": [],
  "scan": null,
  "results": [
    {
      "scope_kind": "path",
      "root": { "display": "/Applications", "lossy": false },
      "scan_id": "…",
      "items": 172266,
      "bytes": 1920503
    }
  ]
}

Full Disk Access

macOS keeps some folders, such as Mail, Messages and Safari, from apps without Full Disk Access. census gets it from whatever started it:

• In the app, the app starts census, so the access you gave Disk Census covers it.
• In Terminal, census has Terminal’s access, not the app’s. To include those folders, add Terminal under System Settings › Privacy & Security › Full Disk Access, then reopen Terminal. The same goes for iTerm, an editor’s terminal, or the app an AI agent runs in.

Check what the current process has:

census access --json

results.status is granted, not_granted or unknown. Without access, the folders a scan couldn’t read count as Hidden space, the scan can end as partial (exit code 4), and coverage_details.access_hint is full_disk_access_required.

Other users’ files

Other people’s home folders on the Mac are counted in Hidden space. To include them, scan with sudo:

sudo census scan

The saved scan and its history belong to you, the user who ran sudo, so later queries without sudo read them. Commands that delete refuse to run as root (run_as_root), so never use sudo to clean.