User Guide

Welcome! This guide walks you through everything Volume Atlas can do — from your first scan to tracking down that mystery folder eating half your disk. You don’t need to read it front to back; jump to whatever you’re trying to do.

A quick note on the command line: Volume Atlas also comes with volume-atlas, a terminal tool that runs the same scanner. It only lands on your PATH when you install the .pkg (it goes to /usr/local/bin/volume-atlas), or when you install it yourself from Settings → CLI Tool. If that’s your thing, the CLI Reference has you covered.

Contents

1. Getting started (and Full Disk Access)
2. Finding your way around
3. Pointing it at something to scan
4. The sidebar
5. The File List
6. The File Atlas
7. Doing something with what you find
8. Settings
9. How Volume Atlas measures size
10. When something looks off

Getting started (and permissions)

Here’s the reassuring part: scanning only reads file information. Volume Atlas never opens, moves, or changes your files while it measures them.

When you open Volume Atlas the first time, it doesn’t go charging off scanning your disk. It shows you your drives and asks what you’d like to measure. A whole drive can take a while, and it’s the wrong place to start if you only came to look at one folder. Pick a drive, or choose a specific folder — either way, nothing happens until you say so. (Prefer it to just get going? See Settings → General.)

What happens next depends on which version you have, and it’s worth knowing which one you’re running.

If you installed the .pkg (Developer ID)

Grant Full Disk Access once and everything works:

1. Open System Settings → Privacy & Security → Full Disk Access.
2. Switch on Volume Atlas.
3. Relaunch the app.

macOS keeps apps out of sensitive places — your Desktop, Documents, Downloads, other people’s home folders, your Photos library — unless you say otherwise. Without this, those get skipped and your totals come up short. Volume Atlas will tell you when that’s happened (see When something looks off), but it’s easier to just grant it up front.

If you got it from the Mac App Store

This version is sandboxed, which means it can only read what you point it at. It can still scan a whole drive — you just have to hand it over first:

1. Pick the drive on the opening screen.
2. macOS shows a Grant Access panel with that drive already selected. Click Grant Access.

That’s it. Your choosing it is the permission — there’s no System Settings trip, and no Full Disk Access involved. Volume Atlas remembers the drive, so you’ll only ever do this once per drive.

Two things you may notice, both normal:

• The first scan may ask about your music and video activity. That’s for measuring your media libraries. Allow it, or those libraries count as zero and your total will be short.
• On a later launch, macOS may ask separately about Desktop, Documents and Downloads. That’s macOS being thorough, not Volume Atlas asking twice — answer once and it won’t come back.

Finding your way around

Before your first scan the window is just the drive picker — no sidebar, no toolbar clutter. There’s nothing to say about a disk nobody’s measured yet. Once results come in, the rest appears:

• The toolbar along the top holds the drive picker in the middle, the File List / File Atlas switch, and a Scan button to refresh. Two small icons can show up here:
  • ⚠️ (amber) — the disk has changed since your last scan, so the numbers may be a little stale. Hit Scan for fresh ones.
  • A circle or triangle — some things couldn’t be read, so the totals are light. Hover it and it’ll tell you what. More on that in When something looks off.
• The sidebar on the left has three sections: your volumes, a file-type breakdown, and any custom folders you’ve added.
• The main area on the right shows whichever view you’ve picked — the File List or the File Atlas.

While a scan is running, the views pause and you’ll see progress along with a rough time remaining. If you’d rather not babysit it, turn on “Notify when a scan completes” in Settings and go do something else.

Pointing it at something to scan

You’ve got four ways to choose what gets measured:

• The opening screen. Every drive on your Mac, as a card showing its name, what kind it is, and how full it is. Plug in a USB drive and it appears straight away. This is what you see before there’s anything to look at, and it’s the quickest way in.
• A whole drive. Use the drive picker in the toolbar once you’ve got results up.
• A specific volume. Pick one from the Current Volumes section of the sidebar.
• Just a folder. Choose one from the opening screen, or add it under Custom Locations. Handy when you only care about, say, ~/Downloads or a project directory. Folders you’ve scanned before stick around in a recents list so you can hop back anytime.

Volume Atlas remembers each scan, so flipping between drives and folders is instant — it won’t re-scan unless you ask. When you do want a fresh look, press Scan; that also re-checks for drives you’ve just plugged in (and forgets ones you’ve ejected).

Scanning network shares and cloud storage: Volume Atlas can scan network drives (NAS, SMB/AFP shares) and cloud-synced folders the same way it scans local ones. Just be aware that the scan speed is limited by your network connection and the speed of the remote share — not your Mac’s disk. A scan that takes seconds on an internal drive can take several minutes or more over the network. This is expected; just let it run.

The sidebar

Current Volumes

The header tells you what kind of drive you’re looking at, and for multi-partition drives, how many partitions there are (something like Internal Drive · 2 Partitions). Each volume shows:

• Its name and a little filesystem badge — APFS, HFS+, ExFAT, FAT32, NTFS, or Network.
• A “Startup Disk” badge on whichever volume you booted from.
• A slim usage bar that shifts color as things fill up: blue when you’ve got room, orange past 75%, and red once you’re over 90% and should probably start clearing space.
• A plain-English used-of-total line, like 453 GB of 1.99 TB.

File Types / Filter

Once a scan finishes, every file type with anything in it shows up here, biggest first — with an icon, a size, a colored bar, and its slice of the pie. Click any category to filter the File List down to just those files. Here’s what goes where:

Don’t agree with where something landed? You get the final say — head to Settings → File Types and move extensions around however you like.

Custom Locations

Hit + to add a folder to scan, and it’ll remember your recent ones (up to ten). This is the spot to zero in on a single trouble area instead of a whole drive.

The File List

This is the spreadsheet-style view — a sortable table of your files. When you’ve filtered to a category, a header up top reminds you which one, its total size, and a one-line description of what it covers.

Two ways to look

A toggle in the list’s toolbar flips between:

• List — a flat run of files, biggest first. This is the “just show me what’s huge” view.
• Tree — the actual folder structure, so you can open things up level by level.

The columns

You get Name, Kind, Date Modified, Size, and % (how much of the total scan a file represents). Click any column header to sort by it.

Sorting (in List mode)

The sort menu covers the usual suspects — largest or smallest first, name A–Z or Z–A, newest or oldest, and by kind.

Spotting files you’ve forgotten about

This one’s a gem. In the same sort menu, File Aging flags big files you haven’t touched in a while — 30, 60, or 90 days — based on when you last opened them. Flagged files jump to the top with an amber clock badge, which makes “old and large” exactly the combination worth cleaning up easy to find. Set it to Off when you don’t need it.

Searching

Just start typing to narrow the list down by name.

The File Atlas

If the File List is the spreadsheet, the File Atlas is the map. It’s a sunburst — the folder you’re focused on sits in the center, and each ring moving outward goes one level deeper. Slices are sized by how much disk they use, so the big stuff jumps right out at you.

Getting around

• Click a slice to dive into that folder — it becomes the new center, with a smooth animation (which you can switch off in Settings if you’d rather it snap).
• Click the center hub to back out one level.
• Use the breadcrumb along the top to see where you are and jump straight back to any level — even several at once, in one fluid move.
• Double-click a slice to reveal it in Finder.
• Hover over anything to highlight it and see the details; the breakdown panel keeps pace.

The knobs

• Color mode — Category paints each slice in its file-type color, Size turns it into a heat map (bigger, older files glow hotter), and Multi-Color gives every branch its own vivid hue. Multi-Color is the default, and it’s lovely for getting your bearings.
• Depth — how many rings to show at once, from 2 up to 8.

The Folder Breakdown panel

Off to the side, you get a ranked rundown of whatever folder you’re focused on — icon, a little bar tinted to match its slice, name, size, and percentage. A couple of nice touches:

• An “Other Objects” row gathers up all the tiny long-tail items into one tidy entry. Hover it and right-click to Show in Finder, Copy Paths, or Move to Trash for the whole bunch at once.
• A Free space row at the top of a volume, so you can see your headroom right next to what’s using it.

Rows light up in sync with the chart, clicking one drills in, and right-clicking gives you the usual file actions.

Doing something with what you find

Finding the space hog is only half the job. Right-click any file — or a whole selection — in the File List or the File Atlas breakdown, and you’ll get:

• Show in Finder — pop it open where it lives.
• Quick Look — peek at it without opening the app it belongs to.
• Get Info — the familiar Finder info panel.
• Copy Path — grab the full path for pasting elsewhere.
• Move to Trash… — with a confirmation first. If something refuses to budge (locked or protected), Volume Atlas offers to reveal it in Finder so you can sort it out by hand.

Select several things at once (⌘-click or ⇧-click) and the actions apply to all of them — the menu even counts them for you, like Move 3 Items to Trash….

Settings

Open Settings with ⌘,. There are three tabs.

General

• File size units — decimal (GB) or binary (GiB), whichever you think in.
• Show hidden files in scans — count the dotfiles too.
• Color-code file sizes by size — tint sizes by how big they are, so large files stand out.
• Size Color Thresholds — decide where “big,” “medium,” and “small” begin (and pick the colors for each). They have to step down — High > Mid > Low — and there’s a reset if you overshoot.
• File Atlas Animation — keep or skip the sunburst’s drill-in/out motion.
• Text size — bump everything up a notch (or three) if the dense layout is hard on the eyes.
• Notifications — get a ping when a scan wraps up.
• On Launch — by default Volume Atlas opens on the picker and asks what you’d like to measure. Turn on “Scan the startup disk when Volume Atlas opens” to skip that and go straight to scanning your startup disk. (On the Mac App Store version this only kicks in for a drive you’ve already granted — otherwise you’d get a permission panel the moment you opened the app, which nobody enjoys.) Mac App Store version only: “Grant access to all drives at once” lets you approve every attached drive together from the picker instead of one at a time. Off by default.
• Diagnostics — toggle Enable verbose logging to write detailed diagnostic entries to the system log (at notice level, so they survive app restarts and are visible in Console.app). Useful when troubleshooting missing drives, unexpected scan results, or settings that don’t seem to be applying. Click Open Console… to launch Console.app directly, then filter by subsystem com.OD.VolumeAtlas to see only Volume Atlas entries. Off by default — leave it off unless you’re actively troubleshooting.

File Types

This is where you teach Volume Atlas your filing system. Add, remove, or shuffle file extensions between categories — an extension only ever lives in one category, so dropping it somewhere new moves it there. Restore Defaults puts everything back. Changes kick in on your next scan.

Right below that, Excluded Paths lets you list folders to skip entirely on every scan — perfect for caches, backups, or anything you’d rather not count.

CLI Tool

Install the volume-atlas command-line tool from here. On the Developer ID build it’s linked into ~/.local/bin (make sure that’s on your PATH), and the .pkg also drops it system-wide at /usr/local/bin. The CLI Reference takes it from there.

How Volume Atlas measures size

A few things are worth knowing so the numbers make sense:

• It reports actual on-disk size — the space a file really occupies — so its totals line up with du and with the free space you’d actually get back. One wrinkle: because APFS can clone files (two files sharing the same underlying storage), a folder’s logical byte count can look bigger than its real footprint. Volume Atlas shows you the honest “how much would I reclaim” figure.
• Apps are measured whole. A .app is counted as a single item covering the entire bundle — nested frameworks, helpers, the lot — the way you naturally think of an app’s size.
• Photos and Music libraries are measured whole, too. Your Photos library is one item with a real size, not thousands of internal files you can’t do anything about individually. macOS may ask permission the first time it’s measured — worth allowing, since these are often among the biggest things on a Mac, and a library that can’t be read counts as zero.
• It never follows aliases or symlinks and stops at the edge of each volume, so nothing gets counted twice. Hardlinked and cloned files are de-duplicated too.
• Decimal vs. binary only changes how the numbers read, not how they’re measured.

When something looks off

• The totals seem too low, or a folder shows 0 KB. Almost always it’s missing Full Disk Access (see the top of this guide) — or the folder’s sitting in your Excluded Paths.
• There’s a small icon in the toolbar saying things couldn’t be read. Hover it; it explains itself. Two flavours:
  • A muted circle — a handful of files were unreadable. Usually harmless; the odd locked or in-use file barely moves the totals.
  • An amber triangle — something was refused entirely, and it names it. This one’s worth acting on: an item that can’t be read counts as zero, so if it’s your Photos library, your total could be short by tens of gigabytes. Grant the permission it’s asking for and scan again.
• That ⚠️ “scan may be out of date” icon showed up. The disk changed in a meaningful way since you scanned. Press Scan for fresh numbers. It’s tuned to stay quiet through ordinary background activity, so when it speaks up it usually means something real moved.
• A scan is taking much longer than expected. If you’re scanning a network share or a cloud-backed folder (a NAS, an SMB/AFP share, or a folder synced by a service like Dropbox or OneDrive), the scan runs at the speed of your network and the remote share — not your local disk. Scans that finish in seconds locally can take several minutes or more over the network. This is normal; let it run. Local APFS scans should still complete quickly.
• “Other” is suspiciously huge. Some file type isn’t categorized the way you’d expect. Sort the offenders out in Settings → File Types and rescan.
• Hunting for stuff to delete? Try File List → Sort → File Aging → Not opened in 90 days — big and forgotten, served up first.
• Need a report you can save or send? The CLI is great for that, including pulling a quick space report from a machine over SSH.
• Still stuck, or found a bug? Go to Help → Send Feedback or Question… — a dialog will show our support address (VAS@orbitdynamic.com) with options to open it in Mail or copy it to paste into whichever email client you use. You can also visit orbitdynamic.com/VolumeAtlas for updates and additional resources.