DEV Community

poolion
poolion

Posted on

Disk Analyzer CLI: A Minimal Python Tool to View Disk Usage by File Extension

#python #opensource #productivity #cli

Disk Analyzer CLI: Quick Disk Space Overview in Pure Python

Sometimes you need to quickly see what's taking up space in your projects folder. This minimal CLI tool analyzes a directory and shows disk usage broken down by file extension — all using only Python's standard library.

What It Does

Scan any directory and get two views of disk usage:

  1. Summary mode: Top N extensions by size (default 15)
  2. Full breakdown mode: All extensions sorted by space consumed

It walks the directory tree, sums file sizes per extension, and formats everything in human-readable units (KB, MB, GB, TB).

Installation

No dependencies needed — just drop the disk-analyzer.py file anywhere:

# Make executable on Unix
chmod +x disk-analyzer.py

# Run directly
python disk-analyzer.py summary -s /path/to/directory
Enter fullscreen mode Exit fullscreen mode

Or place it in your PATH and run as a command.

Usage Examples

Quick overview of a directory 

python disk-analyzer.py summary -s ~/projects
Enter fullscreen mode Exit fullscreen mode

This shows the top file extensions by size in your projects folder.

Deep scan with full breakdown 

python disk-analyzer.py by-ext -s /home/user/downloads -d 0
Enter fullscreen mode Exit fullscreen mode

The -d 0 flag scans the entire directory tree, not just shallow levels.

Show only the largest extensions 

python disk-analyzer.py summary -n 10
Enter fullscreen mode Exit fullscreen mode

Display just the top 10 space-hungry file types (often useful to find large media files or caches).

Command Syntax 

python disk-analyzer.py <mode> -s <dir> [options]

Modes:
  summary     Show top N extensions by size
  by-ext      Full breakdown sorted by size desc

Options:
  -s, --src-dir   Directory to analyze (required)
  -d, --depth     Scan depth (0=all, default=2)
  -n, --top-count Number of top extensions for summary (default=15)
Enter fullscreen mode Exit fullscreen mode

Code Overview

The tool uses os.walk() to traverse directories and accumulate sizes per extension. Here's the core logic:

def analyze_directory(source_dir, depth_limit=0):
    usage_by_ext = {}

    for root, dirs, files in os.walk(source_dir):
        for f in files:
            fp = os.path.join(root, f)
            size = os.path.getsize(fp)
            _, ext = os.path.splitext(f.lower())
            ext = ext or '_noext'

            usage_by_ext[ext] = usage_by_ext.get(ext, 0) + size

    return {'usage_by_ext': usage_by_ext, 'total_size': sum(usage_by_ext.values())}
Enter fullscreen mode Exit fullscreen mode

Permissions errors are caught and skipped gracefully — inaccessible files don't crash the tool. Files without extensions are grouped as _noext or _no_extension in the output.

Use Cases

  • Git prep: Find large files before committing to avoid bloating your repo
  • Downloads cleanup: Audit what's stored in ~/downloads by type
  • Storage audit: Identify which extension family dominates disk usage (logs, images, archives, etc)
  • Troubleshooting: Quickly determine if /var/log is blowing up with .log files or something else

Output Example 

342 MB used in /home/user/projects:

Top 15 file extensions by size:
   1. _no_extension                       128 MB
   2. .png                                 89 MB
   3. jpg                                   37 MB
   4. txt                                   25 MB
   5. .py                                   18 MB
   6. .log                                  31 MB
Enter fullscreen mode Exit fullscreen mode

In full breakdown mode, it lists all extensions sorted by size — useful for seeing every file type contributing to disk usage.

Why Build This?

Sometimes the simplest tool is also the best. Disk space management doesn't need complex UIs or heavy frameworks. A few lines of pure Python can answer: "What's eating my disk?" instantly.

This tool demonstrates minimal viable thinking — solve one problem clearly without extra features that don't help your immediate use case.

Source Code

All code is open source and available on GitHub with a permissive license. The implementation is compact enough to read in one sitting, making it a good starting point for learning directory traversal or building similar utilities.

🔗 Repo: https://github.com/Poolion/disk-analyzer-cli

If you find this useful, you can support development: https://www.buymeacoffee.com/poolion

Top comments (0)