Smart File Organizer

Bulk rename and organize files automatically — sort your Downloads chaos, rename photos by EXIF date, and tidy course materials in seconds.

---

What it does

• Organize by file type — automatically sorts files into Images/, Videos/, Documents/, Audio/, Archives/, Code/, and more
• Organize by date — moves files into 2024/03/ style folders using EXIF data (for photos) or file-modified date
• Bulk rename by pattern — rename hundreds of files using tokens like {year}-{month}-{day}_{name} or photo_{counter}
• EXIF-aware — reads the actual date a photo was taken, not just when it was downloaded
• Dry-run mode — preview every change before anything is touched
• Safe by default — never overwrites files; appends (1), (2), etc. on name collisions
• Clean up empty folders — after organizing, remove leftover empty directories

---

Install

Option 1 — pip (recommended)

pip install smart-file-organizer

With EXIF photo support:

pip install "smart-file-organizer[exif]"

With everything:

pip install "smart-file-organizer[all]"

Option 2 — from source

git clone https://github.com/nord342/smart-file-organizer.git
cd smart-file-organizer
pip install -e ".[all]"

---

Quick start

# Sort your Downloads folder by file type
sfo organize ~/Downloads --by-type

# Preview first (dry run — nothing is moved)
sfo organize ~/Downloads --by-type --dry-run

# Organize photos into year/month folders using EXIF date
sfo organize ~/Photos --by-date --date-format "%Y/%m" --use-exif

# Bulk rename photos: 2024-03-15_001.jpg, 2024-03-15_002.jpg, …
sfo rename ~/Photos --pattern "{date}_{counter}" --use-exif

# Rename files: holiday_001.jpg, holiday_002.jpg, …
sfo rename ~/Downloads --pattern "holiday_{counter}" -e jpg -e png

# Remove empty folders left after organizing
sfo clean ~/Downloads

---

Commands

sfo organize

Moves files into subfolders automatically.

sfo organize SOURCE [OPTIONS]

Arguments:
  SOURCE        Folder to organize

Options:
  --by-type         Sort by file type: Images/, Videos/, Documents/, … (default)
  --by-date         Sort by date: 2024/03/ style folders
  -d, --dest PATH   Destination root (default: same as SOURCE)
  --date-format     strftime date folder format (default: %Y/%m)
  --use-exif        Use EXIF date for photos (default: on)
  -r, --recursive   Also process subfolders
  --dry-run         Preview without moving anything

File type categories:

Folder	Extensions
Images	jpg, jpeg, png, gif, bmp, tiff, webp, heic, raw, cr2, nef, arw, dng, svg, …
Videos	mp4, mov, avi, mkv, m4v, wmv, flv, webm, …
Audio	mp3, flac, wav, m4a, aac, ogg, opus, …
Documents	pdf, doc, docx, txt, md, xls, xlsx, csv, ppt, pptx, epub, …
Archives	zip, tar, gz, bz2, rar, 7z, …
Code	py, js, ts, html, css, go, rs, java, c, cpp, json, yaml, …
Executables	exe, dmg, pkg, deb, msi, …
Other	everything else

---

sfo rename

Bulk renames files using a pattern template.

sfo rename SOURCE --pattern PATTERN [OPTIONS]

Arguments:
  SOURCE            Folder containing files to rename

Options:
  -p, --pattern     Naming template (required) — see tokens below
  --use-exif        Use EXIF date for photos (default: on)
  --start-counter   Starting number for {counter} (default: 1)
  --counter-pad     Zero-pad width for {counter} (default: 3 → 001)
  -e, --ext EXT     Only rename files with this extension (repeatable)
  -r, --recursive   Also rename files in subfolders
  --dry-run         Preview without renaming anything

Available tokens:

Token	Description	Example
{name}	Original filename (no extension)	IMG_4821
{ext}	File extension (no dot)	jpg
{date}	Full date as YYYY-MM-DD	2024-03-15
{year}	4-digit year	2024
{month}	2-digit month	03
{day}	2-digit day	15
{hour}	Hour (24h)	14
{minute}	Minute	32
{second}	Second	07
{counter}	Zero-padded counter (see --counter-pad)	001

---

sfo clean

Removes empty folders.

sfo clean SOURCE [--dry-run]

---

Real-world examples

Tidy a chaotic Downloads folder

sfo organize ~/Downloads --by-type --dry-run   # preview
sfo organize ~/Downloads --by-type             # apply
sfo clean ~/Downloads                          # remove empty folders

Before:

Downloads/
  invoice_march.pdf
  family_vacation.jpg
  project.zip
  screen_recording.mov
  notes.txt
  setup.dmg

After:

Downloads/
  Documents/
    invoice_march.pdf
    notes.txt
  Images/
    family_vacation.jpg
  Archives/
    project.zip
  Videos/
    screen_recording.mov
  Executables/
    setup.dmg

---

Rename 500 holiday photos by EXIF date

sfo rename ~/Photos/Holiday --pattern "{date}_{counter}" --use-exif --dry-run
sfo rename ~/Photos/Holiday --pattern "{date}_{counter}" --use-exif

Before: IMG_4821.jpg, DSC_0042.jpg, photo (1).jpg

After: 2024-07-14_001.jpg, 2024-07-14_002.jpg, 2024-07-15_003.jpg

---

Organize course materials

sfo organize ~/Downloads/CourseFiles --by-type -d ~/Courses/Python101

Before: lecture1.mp4, notes.pdf, exercise.py, slides.pptx

After:

Courses/Python101/
  Videos/lecture1.mp4
  Documents/notes.pdf  slides.pptx
  Code/exercise.py

---

Sort photos into year/month folders

sfo organize ~/Photos --by-date --date-format "%Y/%m" --use-exif

After:

Photos/
  2023/
    06/ (photos taken June 2023)
    12/ (photos taken December 2023)
  2024/
    03/ (photos taken March 2024)

---

Requirements

• Python 3.10+
• click (installed automatically)
• Pillow — optional, for reading EXIF dates from photos (pip install "smart-file-organizer[exif]")
• pyyaml — optional, for YAML config files (pip install "smart-file-organizer[config]")

---

Contributing

Pull requests are welcome. To get started:

git clone https://github.com/nord342/smart-file-organizer.git
cd smart-file-organizer
pip install -e ".[all]"
pip install pytest
pytest

---

License

MIT — free to use, modify, and distribute. See LICENSE.

---

Keywords: bulk file renamer, file organizer script, organize downloads folder, rename photos by date, EXIF photo organizer, batch rename files, sort files by type, media organizer, python file organizer, automatic file sorter