disk-usage

A zero-dependency Python disk usage analyzer. Like ncdu and dust, but portable and scriptable.

Features

• Scan directories and show largest items first
• Tree view with sizes and percentage bars
• Flat list mode (top N largest items)
• Filter by minimum size
• Configurable depth limit
• Show/hide hidden files
• Sort by size or name
• Interactive drill-down mode
• Export results as JSON
• Compare two directories side by side
• Zero dependencies -- just Python 3.6+

Usage

# Analyze current directory
python3 disk_usage.py

# Analyze a specific path
python3 disk_usage.py /var/log

# Limit depth to 2 levels
python3 disk_usage.py -d 2 ~/projects

# Show only items larger than 10MB
python3 disk_usage.py -m 10M /home

# Flat list of top 30 largest items
python3 disk_usage.py -f -n 30 ~/Documents

# Include hidden files
python3 disk_usage.py -a ~/.config

# Sort by name instead of size
python3 disk_usage.py -s name /etc

# Export to JSON
python3 disk_usage.py -j report.json /var

# Compare two directories
python3 disk_usage.py /data/backup-old --compare /data/backup-new

# Interactive mode (drill into directories)
python3 disk_usage.py -i /home

Output Examples

Tree View (default)

  1.2 GB [####################] 100.0% myproject
      --- 800.5 MB [#############       ]  65.2% node_modules/
      ---  250.3 MB [####                ]  20.4% .git/
      ---  100.0 MB [##                  ]   8.1%  build/
      ---   50.2 MB [#                   ]   4.1%  src/
      ---   10.0 MB [                    ]   0.8%  docs/

Flat View

Top 5 items by size in /home/user/project:

    512.3 MB [###########    ]  42.0% /home/user/project/node_modules
    200.1 MB [####           ]  16.4% /home/user/project/.git/objects
    100.0 MB [##             ]   8.2% /home/user/project/build/bundle.js
     50.5 MB [#              ]   4.1% /home/user/project/data/db.sqlite
     25.0 MB [#              ]   2.0% /home/user/project/assets/video.mp4

Interactive Mode

============================================================
  /home/user/projects  (2.5 GB)
============================================================

    0. >    1.2 GB [##########     ]  48.0% webapp/
    1. >  800.0 MB [######         ]  32.0% api-server/
    2. >  300.0 MB [##             ]  12.0% shared-libs/
    3.      200.0 MB [##             ]   8.0% data.sql

  Enter number to drill in, 'u' for up, 'q' to quit:
  > 0

Options

Flag	Description
path	Directory to analyze (default: .)
-d, --depth N	Max depth to display
-n, --top N	Show top N items in flat mode (default: 20)
-m, --min-size SIZE	Min size filter (1M, 500K, 1G)
-s, --sort {size,name}	Sort order (default: size)
-a, --all	Show hidden files/directories
-f, --flat	Flat list instead of tree
-i, --interactive	Interactive drill-down mode
-j, --json FILE	Export tree as JSON
--compare DIR	Compare with another directory

License

MIT