Taming Folder Chaos: Building a Simple Python CLI for Auto File Organization

ahmedul kabir — Sat, 18 Oct 2025 16:23:43 +0000

Hey DEV community! 👋 As a software engineer who's constantly juggling code, downloads, and random files, I got fed up with messy folders.

My Downloads directory was a warzone of images, PDFs, ZIPs, and who-knows-what. So, I built Auto File Organizer—a lightweight Python CLI tool that sorts files into neat subfolders based on extensions. No bloat, no dependencies, just pure stdlib magic.

We've all been there: Searching for that one PDF in a sea of screenshots and archives. Manual sorting? Ain't nobody got time for that. This tool automates it, categorizing files into folders like:

Images (.jpg, .png, etc.)
Documents (.pdf, .docx, etc.)
Archives (.zip, .rar, etc.)
Videos (.mp4, .mkv, etc.)
Audio (.mp3, .wav, etc.)
Code (.py, .js, etc.)
Misc (catch-all for the rest)

It handles duplicates by renaming and skips directories to avoid mishaps.

Why I Built It (and Open-Sourced It)

I'm a fitness freak by day (or whenever I can squeeze in a workout), but coding is my jam. This started as a quick script for personal use, but I realized it could help others—devs, creators, or anyone with digital hoarding tendencies. Open-sourcing it on GitHub (MIT license) lets folks fork and tweak it. Plus, it's a great starter project for Python beginners.
Key decisions:

No deps: Sticks to os, shutil, and argparse for portability.
CLI-first: Easy to run from terminal, with options for flexibility.
Small scope: Under 100 lines—hackable without overwhelm.

How It Works: A Quick Dive
Here's the core logic (full code in the repo):
pythonimport os
import shutil
import argparse

`# ... (category definitions)

def organize_files(directory, recursive=False, dry_run=False, move_noext=False):
# Scan and move logic here...
pass # See repo for full implementation

if name == "main":
parser = argparse.ArgumentParser(description="Organize files by type.")
# Add args: directory, --recursive, --dry-run, --move-noext
args = parser.parse_args()
organize_files(args.directory, args.recursive, args.dry_run, args.move_noext)`

To try it:

Clone: git clone https://github.com/ahmedul/auto-file-organizer.git
Preview: python3 file_organizer.py ~/Downloads --recursive --dry-run
Run: python3 file_organizer.py ~/Downloads --recursive --move-noext

It previews moves in dry-run mode, so no surprises!

Lessons Learned

Testing is key: I added unit tests after a near-miss with recursive moves.
Community input: Early feedback on Reddit led to --move-noext for extensionless files.
Promotion matters: Sharing on X and HN got initial stars—thanks, folks!

What's Next?

Custom config files for user-defined categories.
Undo logs for reversing changes.
Scheduling (e.g., cron integration).

If this resonates, check out the repo: https://github.com/ahmedul/auto-file-organizer. Star it ⭐, fork it, or drop a PR with ideas. What pain points do you have with file management?

Let's discuss in the comments!
Thanks for reading—happy organizing! 🚀

python #opensource #cli #productivity #devtools

DEV Community: ahmedul kabir

Taming Folder Chaos: Building a Simple Python CLI for Auto File Organization

python #opensource #cli #productivity #devtools