A lightweight, modern Python desktop application built with Tkinter to automatically organize cluttered directories into clean, categorized folders by file type.
- One-Click Organization: Automatically scans top-level files in any selected directory and organizes them into categorized folders (Images, Documents, Media, Code, Archives, Installers, and Other).
- Custom Preset & Category Management: Create, edit, and delete custom sorting profiles. Define target directory names, add/remove file extensions, and resolve extension collisions automatically.
- Persistent Configuration: User presets, target folders, and custom rules automatically persist across application sessions via
config.json. - Duplicate File Detection & Removal: Accurate, byte-level content hashing (MD5) to identify and safely delete duplicate files regardless of differing filenames.
- Delete Only Mode: Perform targeted cleanups (e.g., removing duplicates or pruning empty directories) without sorting files into subfolders.
- Empty Directory Cleanup: Safely scans and prunes empty top-level directories post-operation.
- Permanent Deletion Safety Warning: Modal confirmation prompt protecting against accidental data loss when destructive deletion options are selected, complete with a persistent suppression toggle.
- Undo Sort Action: One-click transaction history reversal to restore moved files back to their original root locations and clean up newly empty category folders matching the active preset.
- Threaded Background Execution & Progress Bar: Offloads scan and undo I/O to background daemon threads with real-time visual progress tracking to prevent UI lockups.
- Live Action Console: Embedded real-time log window displaying detailed file movements, skipped items, and operation summaries.
- Safety First: Prevents overwriting duplicate filenames and gracefully handles locked or permission-restricted system files.
- Modern UI: Built with a clean, flat aesthetic, dedicated options sidebar, and modal configuration dialogs.
The following features and milestones:
- Delete Empty Folders: Post-scan cleanup to safely remove empty top-level subdirectories.
- Delete Only Mode: Bypass category organization to execute targeted deletions and cleanup tasks.
- Duplicate File Detection: Byte-level content hashing (MD5) to identify and isolate duplicate files.
- Background Execution & Progress Bar: Offloading scan I/O to a background thread with real-time visual progress tracking.
- Undo Action: Transaction history logging to reverse the last declutter run and restore original file locations.
- Custom Preset & Category Editor: Profile manager saving custom folder rules and file mappings to
config.json. - Permanent Deletion Confirmation Modal: Warning dialog triggered before destructive tasks with configurable suppression.
- Language: Python 3.x
- GUI Framework: Tkinter / ttk
- Concurrency:
threading - File Management & Hashing: Standard Library (
os,shutil,hashlib,json) - Executable Build: PyInstaller
- Python 3.10+ installed on your system.
- Clone the repository:
git clone [https://github.com/Tyler-Gushue/desktop-declutter.git](https://github.com/Tyler-Gushue/desktop-declutter.git) cd desktop-declutter - Rune the applicatoin:
python src/gui.py
desktop-declutter/
├── src/
│ ├── cleaner.py # Core file scanning, categorization, and filesystem movement logic
│ ├── gui.py # Tkinter UI layout, event loop, and live logging console
│ └── Logo.png # Application window and taskbar icon
├── .gitignore # Git ignore file (excludes __pycache__, build artifacts, etc.)
└── README.md # Project documentation and roadmap