bulk file organizer

a python script that cleans up a messy folder (like your Downloads) by sorting files into subfolders by type, and by month too if you want.

it's built to be safe: it shows a preview first, never overwrites anything, and can undo every run.

no extra libraries needed, just python 3.

what it does

• sorts files into Images/, Documents/, Videos/, Archives/, Code/ and more (60+ file types)
• anything it doesn't know goes into Other/
• optional --by-date mode: Images/2026-10/, Images/2026-09/ ...
• preview by default, nothing moves until you add --go
• name clash? notes.txt becomes notes (1).txt, never overwritten
• --undo puts everything back, one run at a time, and removes the empty folders it made
• the undo log is saved even if it crashes or you hit ctrl+c halfway
• skips hidden files and subfolders that are already there

setup

git clone https://github.com/<your-username>/file-organizer.git
cd file-organizer

that's it. no pip install.

how to use

1. preview first (nothing gets moved):

python organize.py ~/Downloads

2. do it for real:

python organize.py ~/Downloads --go

3. also split by month:

python organize.py ~/Downloads --go --by-date

4. changed your mind:

python organize.py ~/Downloads --undo

on windows use a path like C:\Users\you\Downloads (or ~/Downloads works in powershell too).

try it safely first

don't trust it on your real downloads yet? make a fake messy folder:

python make_mess.py                     # makes ./messy_downloads with 24 junk files
python organize.py messy_downloads --go
python organize.py messy_downloads --undo

example output

assignment1.pdf  ->  Documents/assignment1.pdf
backup.zip  ->  Archives/backup.zip
holiday.jpg  ->  Images/holiday.jpg
weird_file.xyz  ->  Other/weird_file.xyz
...

summary:
  Archives       2 file(s)
  Documents      4 file(s)
  Images         4 file(s)
  Other          2 file(s)
  ...

moved 24 file(s). changed your mind? run with --undo

adding your own file types

open organize.py and edit the TYPES dict at the top:

"Images": [".jpg", ".png", ...],
"3D Models": [".blend", ".fbx", ".obj"],   # new folder, just add a line

how undo works

every real run saves a list of moves (from -> to) into a hidden .organizer_undo.json file inside the folder you sorted. --undo reads the last run, moves each file back, and deletes the folders that are now empty. run --undo again to go back another run.

built with

• python 3 (pathlib, shutil, argparse, json)

todo maybe

• a --watch mode that sorts new files as soon as they land
• find and flag duplicate files (same content, different names)
• a settings file instead of editing the TYPES dict
• simple gui with a "pick folder" button (tkinter)
• schedule it to run every night (task scheduler / cron)