DEV Community

poolion
poolion

Posted on

File Organizer CLI: Organize Your Downloads by Extension and Date Using Only Python Standard Library

#python #opensource #productivity #cli

File Organizer CLI: A Minimal Python Tool to Organize Files Smartly

I built file-organizer-cli because download folders keep getting messy. This script organizes your files automatically by extension or creation date using only Python's standard library — no pip install needed!

What It Does

The tool scans a directory and groups files into organized subdirectories:

  • By extension: All .jpg, .png, .pdf files get sorted into separate folders
  • By date: Files are grouped by year/month (e.g., 2024/01/, 2024/02/)

You can copy or move files, and even scan to preview grouping without modifying anything.

Features at a Glance

  • Uses only standard library (pathlib, datetime, shutil)
  • Three commands: copy, move, scan
  • Organize by extension or date
  • Simple CLI with argparse
  • Works with any file types

Installation

Drop the code anywhere and run it:

python organize_files.py --help
Enter fullscreen mode Exit fullscreen mode

No pip install, no virtualenv needed!

Usage Examples

1. Copy files by extension to organized folder

I use this for my Downloads folder:

python organize_files.py copy \
    -s ~/Downloads \
    -d ~/Organized \
    -m extension
Enter fullscreen mode Exit fullscreen mode

Result: ~/Organized/./Documents/report.pdf, ~/Organized/.png/./Images/photo.jpg, etc.

2. Move files by creation date

For old photo folders, organize by timestamp:

python organize_files.py move \
    -s ~/Pictures/old-cam-folio \
    -d /media/photos-archived \
    -m date
Enter fullscreen mode Exit fullscreen mode

This creates ~/Pictures-archieved/2023/12/..., 2024/01/..., etc.

3. Scan first to see grouping

Preview how files will be grouped:

python organize_files.py scan -s ~/Downloads
Enter fullscreen mode Exit fullscreen mode

Output looks like:

(    )   124 files
pdf       45 files
txt        89 files
jpg         73 files
png          62 files
Enter fullscreen mode Exit fullscreen mode

How I Built It

The code is straightforward Python with argparse for CLI parsing and pathlib for safe file path handling:

  • argparse handles subcommands (copy, move, scan) and arguments
  • os.walk() traverses directories recursively
  • pathlib.Path safely constructs destination paths
  • datetime.fromtimestamp() extracts date from file mtime (for date-based grouping)
  • shutil.copy2()/shutil.move() handle actual file operations

Key insight: Always construct destination paths by breaking them into parts (date+ext+basename) to avoid path separator issues across different OSes.

Why Build This?

I've written several Python scripts for batch operations, but most require dependencies. This one just works out of the box on any system with Python 3 installed.

It's useful if you:

  • Have a messy downloads folder you want to clean up
  • Need to archive old files by date
  • Want a simple CLI tool without setup time

Full Command Reference 

# Copy mode (keeps originals)
python organize_files.py copy -s /path/to/source -d /path/to/dest

# Move mode (permanently relocates files)  
python organize_files.py move -s /path/to/source -d /path/to/dest -m date

# Preview grouping
python organize_files.py scan -s /path/to/folder
Enter fullscreen mode Exit fullscreen mode

The -m flag accepts extension or date. Both commands have a default of extension.

Complete Code Available on GitHub

Want to see the full implementation? The repo is published at:

https://github.com/poolion/file-organizer-cli

If you find this useful, you can support development: https://www.buymeacoffee.com/poolion

Top comments (0)