Use ncdu on CasaOS when you need to find which folders are actually consuming disk space, but scan the correct host path—not just a tiny container filesystem. For current Linux systems, the upstream project provides static binaries, and ncdu 2.x is the fastest route for interactive disk-usage analysis.
The 2024 BigBear tutorial is useful as an introduction, but you do not need a special app-store container to use ncdu. For storage troubleshooting, a host terminal or a container with an explicitly mounted read-only target is more transparent.
What ncdu Is Good For
ncdu is an interactive disk-usage analyzer. It scans directories, sorts them by size, and lets you drill into large folders without manually chaining du commands.
The current ncdu project page lists ncdu 2.x static binaries for x86_64, ARM, and AArch64.
Start with the Filesystem That Is Actually Full
Run:
df -hIdentify the mount with low free space. Then scan that mount instead of running ncdu blindly from /.
Scan a CasaOS Data Path
Typical examples:
ncdu /DATA
ncdu /media
ncdu /var/lib/dockerThe exact path depends on your installation. If Docker or AppData is the suspected source, inspect that location directly.
Be Careful Scanning Docker Internals
/var/lib/docker contains image layers, writable layers, logs, and metadata. ncdu can show which directories are large, but deleting random overlay files manually can corrupt Docker state.
Use Docker-aware cleanup commands for images, containers, and caches rather than deleting internal layer directories from ncdu.
Containerized ncdu Has a Visibility Limit
If you run ncdu inside a container, it only sees the paths you mount into that container. A scan of the container root tells you almost nothing about total CasaOS disk usage.
If you prefer Docker, mount the target host path read-only and scan that mount. Keep deletion disabled while diagnosing.
Find Large AppData Folders First
Self-hosted apps can accumulate thumbnails, logs, caches, databases, and downloaded metadata. The Docker storage guide explains why host AppData can grow even when container images are small.
Common Large-Space Sources
- media transcode cache;
- container JSON logs;
- database files;
- photo thumbnails and machine-learning indexes;
- download client incomplete folders;
- old backups;
- Docker images and build cache.
Do Not Delete Until You Know What Owns the Folder
Use ncdu to identify the large path, then determine which application owns it. Stop the relevant application before deleting data that may be actively written.
Use Excludes to Make Large Scans More Useful
On a server with mounted network shares, backups, or external disks, scanning the wrong tree can take a long time and mix unrelated storage into one result. Start at the exact mount point shown by df -h and avoid crossing into remote mounts unless they are the problem.
For repeated troubleshooting, ncdu can export scan data so you can compare growth over time instead of rescanning a huge filesystem every session.
Understand Deleted-but-Open Files
Sometimes df reports a full filesystem while ncdu cannot find enough visible files to explain it. One cause is a process holding an already-deleted file open. The directory entry is gone, but the blocks remain allocated until the process closes the file.
When the ncdu total and df disagree significantly, inspect open deleted files with a tool such as lsof +L1 if it is available on the host. Restarting the responsible service can release the space after you understand what it is.
Use ncdu as a Measurement Tool, Not a Cleanup Policy
A large cache may be safe to clear, while a similarly sized database directory may be critical. The value of ncdu is showing where the space went; the owning application should determine how that space is reclaimed.
FAQ
Can ncdu delete files?
Yes, but use deletion cautiously. For Docker internals, databases, and app-managed data, prefer the application's own cleanup workflow.
Why does ncdu show less space than df?
Possible reasons include deleted-but-open files, inaccessible directories, filesystem metadata, snapshots, or data outside the scanned mount.
Do I need BigBearCasaOS to install ncdu?
No. It is one packaging option. Current upstream also provides standalone static binaries.
Where should I scan first?
Use df -h to identify the full mount, then scan that exact path with ncdu.
