sizescan

quickly list the worst offenders eating up drive space

Features

• 📁 Find Largest Files: Traditional file-by-file scanning
• 📂 Find Largest Directories: Identify which directories consume the most space
• 🔍 Find Deep Large Directories: Locate large directories at a minimum depth (sorted by size)
• 🎯 Interactive Mode: Use arrow keys to select what you want to find
• ⚡ Multithreaded Scanning: Parallel processing for faster results
• 🎮 Keyboard Interrupt Handling: Press Ctrl+C to stop scanning and see partial results
• 📊 Live Progress Updates: See current directory being scanned and running counts

Installation

This project uses uv for fast, reliable Python package management.

Install uv (if not already installed)

curl -LsSf https://astral.sh/uv/install.sh | sh

Option 1: Install as a Global Tool (Recommended)

Install sizescan globally so you can use it anywhere without activating a virtual environment:

uv tool install .

Now you can run it from anywhere:

sizescan /path/to/scan -i

To update after making changes:

uv tool install --force .

To uninstall:

uv tool uninstall sizescan

Option 2: Local Development

For local development with a virtual environment:

uv sync

This will create a virtual environment and install all dependencies automatically.

Usage

Interactive Mode (Recommended)

If installed as a global tool:

sizescan /path/to/scan --interactive
# or
sizescan /path/to/scan -i

If using local development:

uv run python sizescan.py /path/to/scan -i

Or activate the virtual environment first:

source .venv/bin/activate  # On Unix/macOS
python sizescan.py /path/to/scan -i

Use arrow keys to select:

• Find Largest Files
• Find Largest Directories
• Find Deepest Large Directories

Command Line Mode

Find largest files (default):

sizescan /path/to/scan
sizescan /path/to/scan --results 20

Find largest directories:

sizescan /path/to/scan --mode directories

Find deep large directories (at minimum depth):

sizescan /path/to/scan --mode deep
sizescan /path/to/scan --mode deep --min-size 100 --min-depth 3  # 100MB, depth >= 3

Note: If using local development mode instead of global install, prefix commands with uv run python sizescan.py instead of just sizescan.

Options

• --results N: Number of results to show (default: 10)
• --mode {files,directories,deep}: Scan mode
• --min-size N: Minimum size in MB for deep scan (default: 10)
• --min-depth N: Minimum depth for deep scan (default: 5)
• --interactive or -i: Use interactive menu
• --no-parallel: Disable parallel processing (slower but uses less memory)
• --threads N: Number of threads for parallel processing (default: auto)

Performance Tips

• Parallel processing is enabled by default for faster scans
• Use --threads 8 to use more CPU cores on larger systems
• Use --no-parallel if you're low on memory or CPU
• Press Ctrl+C anytime to stop scanning and see results found so far

Notes

Run it with sudo otherwise you may get permission errors.