PTDU is a graphical disk usage analyzer built with Python and Tkinter, inspired by ncdu (NCurses Disk Usage). It provides an interactive, navigable tree view of directory sizes with full recursive scanning, vim-like keyboard navigation, SQLite caching, and comprehensive error handling.
- Interactive Tree View: Navigate directories with an intuitive tree interface
- Full Recursive Scan: Complete directory tree scanning for accurate size information
- Background Scanning: All filesystem operations run in separate threads
- Vim-like Navigation: Keyboard-first interface (j/k navigation, h/l expand/collapse)
- Human-readable Sizes: Automatic conversion (B, KB, MB, GB, TB)
- SQLite Caching: Persistent cache for faster subsequent scans
- Virtual Scrolling: Optimized handling of large directories (100k+ items)
- Export: Save scan results to JSON or CSV
- Safe Delete: Move to trash with confirmation
- Cross-platform: Linux, macOS, and Windows support
- Python 3.8+
- Tkinter (usually included with Python)
- send2trash (optional, for safer file deletion)
# Clone the repository
git clone https://github.com/cosmez/ptdu.git
cd ptdu
# Install in editable mode
pip install -e .pip install ptdu# Analyze current directory
ptdu
# Analyze specific directory
ptdu /path/to/directory
# Show help
ptdu --helpptdu [path] [options]
Options:
path Directory to analyze (default: current directory)
--follow-symlinks Follow symbolic links when scanning
--exclude, -e Additional patterns to exclude (multiple allowed)
--max-depth, -d Maximum scan depth
--no-cache Disable SQLite caching
--clear-cache Clear cache before starting
--version Show version information
--help Show help message# Analyze home directory, excluding node_modules and .git
ptdu ~ -e node_modules -e .git
# Scan with limited depth for faster results
ptdu /var -d 3
# Clear cache and rescan
ptdu --clear-cache /path/to/dir
# Follow symbolic links
ptdu --follow-symlinks /path/to/dir| Key | Action |
|---|---|
j or ↓ |
Move down |
k or ↑ |
Move up |
h or ← |
Collapse directory |
l or → |
Expand directory |
Enter |
Toggle expand/collapse |
g |
Jump to top |
G |
Jump to bottom |
u |
Go to parent directory |
| Key | Action |
|---|---|
q |
Quit application |
r |
Rescan current directory |
d |
Delete selected item (with confirmation) |
b |
Toggle breadcrumb/path bar |
o |
Open folder in file manager |
e |
Export scan results (JSON/CSV) |
| Key | Action |
|---|---|
. |
Toggle hidden files (dotfiles) |
s |
Cycle sort mode (Size → Name → Items) |
Ctrl + Plus |
Increase font size |
Ctrl + Minus |
Decrease font size |
Ctrl + 0 |
Reset font size |
- Name - File or directory name with icon (📁/📂/📄)
- Size - Human-readable size
- Size Bar - Visual representation of relative size
- Percent - Percentage of parent directory
- Items - Number of items (directories only)
- Blue - Directories
- Black - Regular files
- Gray - Hidden files (starting with
.) - Orange - Medium files (10-100 MB)
- Red - Large files (>100 MB)
PTDU automatically caches scan results to speed up subsequent scans:
- Cache location:
~/.cache/ptdu/cache.db - Automatic invalidation when directories are modified
- Thread-safe operations
To disable caching:
ptdu --no-cache /path/to/dirTo clear the cache:
ptdu --clear-cache# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install in editable mode with dev dependencies
pip install -e ".[dev]"pytestmypy --strict ptdu/# Run in development mode
python -m ptdu.main
# Or use the installed command
ptduptdu/
├── ptdu/ # Main package
│ ├── __init__.py # Package exports
│ ├── cache.py # SQLite caching
│ ├── errors.py # Error handling
│ ├── fonts.py # OS-aware font configuration
│ ├── main.py # Entry point with CLI args
│ ├── models.py # DirNode data model
│ ├── performance.py # Virtual scrolling, memory optimization
│ ├── scanner.py # Directory scanning
│ ├── threads.py # Background threading
│ ├── treeview.py # Directory tree view widget
│ ├── ui.py # Main window
│ └── utils.py # SizeCalculator utility
├── tests/ # Test suite
│ ├── __init__.py
│ ├── test_models.py
│ ├── test_scanner.py
│ ├── test_threads.py
│ ├── test_treeview.py
│ ├── test_ui.py
│ └── test_utils.py
├── docs/ # Documentation
│ ├── user_guide.md # User documentation
│ └── developer.md # Developer documentation
├── README.md # This file
└── pyproject.toml # Project configuration
- DirNode: Tree node representing files and directories
- Parent-child relationships with size propagation
- Expand/collapse state tracking
- Scanner: High-performance directory scanner using
os.scandir() - ScanResult: Dataclass for scanned entries
- MemoryMonitor: Memory usage tracking
- Pattern-based filtering (skip/exclude)
- Recursive scanning with configurable depth
- ScanCache: SQLite-based caching with mtime invalidation
- Thread-safe operations with locking
- Automatic cache validation
- VirtualScroller: Efficient handling of large directories
- MemoryOptimizer: Memory usage optimization
- LargeDirectoryHandler: Special handling for huge directories
- ErrorHandler: Centralized error handling with dialogs
- PathValidator: Path validation and sanitization
- User-friendly error messages with suggestions
- ScanThread: Background scanning thread
- ScanThreadManager: Thread lifecycle management
- Queue-based message passing
- DirectoryTreeview: Custom Treeview with styling
- Size bars, color coding, icon display
- Node mapping for tree operations
- MainWindow: Main application window
- Keyboard shortcut handling
- Integration with all components
- FontManager: OS-aware font detection
- Dynamic font size adjustment
- Cross-platform font selection
- SizeCalculator: Human-readable size formatting
- Percentage calculations
PTDU is optimized for large directories:
- Virtual Scrolling: Renders only visible items (100k+ items supported)
- Memory Monitoring: Configurable thresholds with warnings
- Depth Limiting:
--max-depthfor limiting recursion - Caching: Persistent SQLite cache reduces re-scan time
Typical performance:
- SSD: 50k-100k files/second
- HDD: 5k-10k files/second
Comprehensive error handling includes:
- Permission denied dialogs with retry/skip/abort options
- Long path warnings (>4000 characters)
- Scan error handling with continue options
- Delete error handling with retry
- Cache error handling (non-critical, continues without cache)
- User Guide:
docs/user_guide.md- Complete user documentation - Developer Docs:
docs/developer.md- Architecture and API documentation
MIT License