DEV Community

poolion
poolion

Posted on

Batch File Mover: A Python CLI Tool for Organizing Files by Extension or Date

#python #opensource #productivity #cli

Batch File Mover: Organize Your Files with a Simple Python CLI

When managing large directories of files, organizing them systematically can be time-consuming. I built batch-mover, a minimal Python CLI tool that helps batch move files by extension or modification date — something that would take hours to do manually but takes seconds with the right automation.

What Problem Does This Solve?

Common file organization tasks include:

  • Moving all images (JPEG, PNG, GIF) from /tmp to /backup/photos
  • Organizing downloads into year-month subdirectories
  • Finding out what types of files you have in a directory without manually checking each one

Manual approaches using shell glob patterns or multiple mv commands are error-prone and hard to maintain. This tool automates these tasks safely with a dry-run mode first.

Key Features

  • Move by extension: Select which file extensions to move (e.g., all .jpg, .png, .pdf)
  • Move by date: Create subdirectories based on file modification dates using strftime patterns
  • Dry-run mode: Preview exactly what will happen before executing moves
  • List files by type: Get a quick overview of file distribution in any directory

Installation

No dependencies required. Copy the single Python file to your system:

cp batch_mover.py ~/bin
chmod +x ~/bin/batch-mover
Enter fullscreen mode Exit fullscreen mode

Then run with python batch_mover.py.

Alternatively, copy to /usr/local/bin:

sudo cp batch_mover.py /usr/local/bin/batch-mover
sudo chmod +x /usr/local/bin/batch-mover
batch-mover --help
Enter fullscreen mode Exit fullscreen mode

Usage Examples

Move all images to a backup directory 

python batch_mover.py move-by-ext \
  --src-dir ~/Photos/Imported \
  --dst-dir ~/Photos/Backup \
  --extension jpg,png,gif,tiff
Enter fullscreen mode Exit fullscreen mode

Preview moves before executing (dry-run) 

python batch_mover.py move-by-ext \
  --src-dir /tmp/downloads \
  --dst-dir ~/Sorted \
  --extension txt pdf log \
  --dry-run
Enter fullscreen mode Exit fullscreen mode

Organize files into year-month directories

This is useful for /var/log, downloads, or any directory with timestamped files:

python batch_mover.py move-by-date \
  --src-dir /var/backups/current \
  --dst-dir /var/backups/organized \
  --pattern '%Y-%m'
Enter fullscreen mode Exit fullscreen mode

The tool creates subdirectories like 2024-12/, 2025-01/, etc., grouped by the file modification time.

List files grouped by extension

Quickly see what you have:

python batch_mover.py list-types \
  --src-dir ~/projects/my-latest-project
Enter fullscreen mode Exit fullscreen mode

Output example:

[.js]: 42 files
[.css]: 15 files
[.html]: 8 files
[.(no extension)]: 3 files
Enter fullscreen mode Exit fullscreen mode

How It Works

The tool uses Python's os.walk() to traverse directories and check file properties:

  • For extension-based moves, it normalizes extensions to lowercase with a dot (e.g., JPG → .jpg) and matches against a provided list. Files are moved atomically using os.rename().

  • For date-based organization, each file's modification time is read via filepath.stat().st_mtime, converted to a date object, then formatted according to the specified pattern (default %Y-%m). Each target subdirectory is created with mkdir(parents=True, exist_ok=True) before renaming the file.

  • The dry-run flag bypasses all actual moves and prints what would happen — perfect for testing your destination structure without risk.

Code Highlights

The implementation is intentionally minimal: no external dependencies, ~120 lines of Python. Key functions include:

  • move_files_by_extension(): Iterates directory trees, matches extensions, renames files
  • move_files_by_date(): Converts file timestamps to date-subdirectory paths
  • list_files_by_type(): Groups relative file paths by their extension

All commands share a common CLI interface using argparse with subcommands for clarity.

When to Use This

  • Migrating legacy directories and reorganizing by type
  • Preparing images or documents for review from a staging folder
  • Creating standardized archive structures from temporary downloads
  • Auditing what file types you have before deciding on cleanup actions

Full Documentation 

batch-mover --help
python batch_mover.py move-by-ext --help
python batch_mover.py move-by-date --help
python batch_mover.py list-types --help
Enter fullscreen mode Exit fullscreen mode

The tool handles common edge cases like files without extensions (grouped as (no extension)) and errors when reading timestamps (skipped silently).

Final Thoughts

File organization shouldn't require writing complex shell scripts or risking data loss with half-baked automation. This tool gives you safe, predictable moves with dry-run validation. The code is intentionally simple: one Python file, no dependencies, MIT license.

Project Repository: https://github.com/Poolion/batch-mover

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

Top comments (0)