A smart, lightweight Python utility to keep your folders organized. Automatically categorizes files into logical subdirectories based on their file extensions.
This repo contains two versions — pick the one that fits your need.
v1 — main.py |
v2 — scanner.py |
|
|---|---|---|
| Level | Beginner-friendly | Advanced |
| Input | Interactive prompt | CLI arguments (--path, --output, --dry-run) |
| Organizes by | File extension → named folders | Extension + Date (YYYY-MM-DD) |
| Duplicate handling | Auto-rename on collision | SHA-256 hash detection, skips true duplicates |
| Recursive scan | ❌ Top-level only | ✅ Full directory tree (rglob) |
| Dry run | ❌ | ✅ Preview changes before moving anything |
| Report output | Console only | Organizer_report.json saved to output folder |
- ⚡ Fast Execution: Instantly analyzes and organizes large directories.
- 📁 Smart Categorization: Pre-defined rules for Images, Documents, Videos, Audio, Archives, Scripts, and more.
- 🛡️ Collision Handling: Automatically renames files if a duplicate exists in the destination (e.g.,
image_1.jpg). - 🧹 Default Fallback: Catches all unknown file types and moves them to an "Others" folder. (v1)
- 🔍 Duplicate Detection: SHA-256 hashing ensures identical files are never moved twice. (v2)
- 📋 JSON Reports: Every run generates a detailed action log. (v2)
- 🛠️ Simple UI: Easy-to-use command-line interface.
| Category | Extensions |
|---|---|
| Images | .jpg, .jpeg, .png, .gif |
| Documents | .pdf, .docx, .txt |
| Videos | .mp4, .avi, .mkv |
| Audio | .mp3, .wav, .aac |
| Archives | .zip, .rar, .tar, .gz |
| Scripts | .py, .js, .sh |
| Other | Everything else! |
v2 note:
scanner.pyorganizes by raw extension (e.g.PDF/,MP4/) rather than the category names above, and adds a date subfolder (PDF/2025-06-01/).
Make sure you have Python installed.
git clone https://github.com/Riya5407/file-organiser.git
cd file-organiserpython main.pyThe script will prompt you for the folder path you wish to clean up.
Enter the path of the folder you want to organize: C:\Users\YourName\Downloads
python scanner.py --path /path/to/source --output /path/to/destinationAvailable flags:
| Flag | Description | Default |
|---|---|---|
--path |
Source folder to scan | ~/Downloads |
--output |
Destination for organized files | ~/Downloads |
--dry-run |
Preview moves without touching any files | false |
Example — preview changes first:
python scanner.py --path ~/Desktop --output ~/Organized --dry-runExample — actually organize:
python scanner.py --path ~/Desktop --output ~/OrganizedA report is saved at <output>/Organizer_report.json after every run.
- Read Dir: Scans all files in the input directory.
- Match Ext: Checks the file extension against pre-defined categories.
- Ensure Folder: Creates the target subfolder if it doesn't already exist.
- Move & Rename: Moves the file safely, handling any naming conflicts gracefully.
- Recursive Scan: Walks the full directory tree, ignoring
.git,node_modules, and__pycache__. - Hash Check: Computes SHA-256 for every file; true duplicates are skipped automatically.
- Date Bucketing: Determines destination path as
<ext>/<YYYY-MM-DD>/using file modification time. - Dry Run (optional): Prints planned moves without touching the filesystem.
- Move & Report: Executes moves and saves a JSON summary of every action.
Contributions are welcome! Feel free to open an issue or submit a pull request if you have ideas for new categories or features.
Distributed under the MIT License. See LICENSE for more information.
Developed with ❤️ by Riya5407