Automate Your File Chaos with Python: A Practical Guide to pathlib and watchfiles

Nobody sets out to have a Downloads folder with 400 unsorted files named image_20260421_final_v3.png. It just happens. Every screenshot, PDF from a random email, installer you needed once, and meme you saved at 2 AM accumulates until the folder is unusable. You could sort it manually. Or you could write about 30 lines of Python and never think about it again.

File automation is one of those things Python does better than almost any other language. The standard library gives you everything you need for basic operations, and a handful of excellent third-party packages fill the gaps for real-time monitoring and cross-platform compatibility. You don’t need a GUI app, a paid tool, or a complicated setup — just Python and the willingness to write the thirty lines that solve the problem once instead of dealing with it manually every week.

This guide covers the core tools — pathlib for path handling, watchfiles for filesystem monitoring — and builds three practical scripts you can drop into your own system today. Each script is self-contained, well under 100 lines, and designed to be customized to your specific directory structure and file types.

Why pathlib Instead of os.path

If you learned Python before 3.4, you probably reach for os.path.join(), os.path.exists(), and os.listdir() by muscle memory. Those still work. But pathlib has been the recommended way to handle paths since Python 3.6, and the API is cleaner, more readable, and handles cross-platform edge cases that os.path doesn’t.

Here’s the difference in practice. With os.path:

import os

downloads = os.path.expanduser("~/Downloads")
for filename in os.listdir(downloads):
    full_path = os.path.join(downloads, filename)
    if os.path.isfile(full_path):
        ext = os.path.splitext(filename)[1].lower()
        target_dir = os.path.join(downloads, ext.lstrip("."))
        os.makedirs(target_dir, exist_ok=True)
        os.rename(full_path, os.path.join(target_dir, filename))

With pathlib:

from pathlib import Path

downloads = Path.home() / "Downloads"
for file in downloads.iterdir():
    if file.is_file():
        ext = file.suffix.lower().lstrip(".")
        target = downloads / ext / file.name
        target.parent.mkdir(exist_ok=True)
        file.rename(target)

The pathlib version reads like a description of what you want to happen, not a series of function calls you have to mentally trace. The / operator overload for path joining alone is worth the switch — downloads / ext / file.name is self-documenting in a way os.path.join(downloads, ext, file.name) never will be.

Organizing Your Downloads Folder

Let’s build a complete script that sorts every file in your Downloads folder into subdirectories by extension. Images go in images/, PDFs in documents/, code files in code/, and everything else goes in an other/ bucket.

The script needs to do four things: scan a directory for files, figure out which category each file belongs to, create the target subdirectory if it doesn’t exist, and move the file there. Each of these operations is a single function call in pathlib, but the details — collision handling, cross-platform move behavior, filtering out directories — are where most people’s first attempt breaks.

Here’s the full script. Save it as organize_downloads.py and run it with python organize_downloads.py.

from pathlib import Path
import shutil

CATEGORIES = {
    "images": {".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg", ".bmp"},
    "documents": {".pdf", ".docx", ".txt", ".md", ".csv", ".xlsx", ".pptx"},
    "code": {".py", ".js", ".ts", ".html", ".css", ".json", ".yaml", ".toml"},
    "archives": {".zip", ".tar.gz", ".rar", ".7z"},
    "videos": {".mp4", ".mov", ".avi", ".mkv"},
    "music": {".mp3", ".wav", ".flac", ".aac"},
}


def categorize_file(file: Path) -> str:
    suffix = file.suffix.lower()
    for category, extensions in CATEGORIES.items():
        if suffix in extensions:
            return category
    return "other"


def organize_downloads(downloads_dir: Path | None = None):
    downloads = downloads_dir or Path.home() / "Downloads"

    moved = 0
    for file in downloads.iterdir():
        if not file.is_file():
            continue

        category = categorize_file(file)
        target_dir = downloads / category
        target_dir.mkdir(exist_ok=True)
        target = target_dir / file.name

        # Avoid overwriting: append a number if the file already exists
        counter = 1
        while target.exists():
            stem = file.stem
            target = target_dir / f"{stem}_{counter}{file.suffix}"
            counter += 1

        shutil.move(str(file), str(target))
        moved += 1
        print(f"Moved: {file.name} -> {category}/")

    print(f"Done. {moved} files organized.")


if __name__ == "__main__":
    organize_downloads()

A few things worth noting in this script. The CATEGORIES dictionary is a mapping from category names to sets of extensions — using a set means O(1) lookup. The collision handling with counter avoids the classic “silently overwrite a file with the same name” bug that beginner scripts tend to ship. And shutil.move is used instead of Path.rename because rename can fail across filesystem boundaries (different drives on Windows, different mount points on Linux), while shutil.move falls back to copy-and-delete when a direct rename isn’t possible.

Watching for New Files with watchfiles

Sorting an existing folder once is useful. Having the script run automatically every time a new file appears is better. The watchfiles library (install with pip install watchfiles) wraps Rust’s notify crate and provides a dead-simple Python API for watching directories.

Here’s a watcher that monitors your Downloads folder and categorizes new files as they arrive:

from pathlib import Path
from watchfiles import watch
import shutil
import time


def auto_organize(directory: Path | None = None):
    watched = str(directory or Path.home() / "Downloads")

    for changes in watch(watched):
        for change_type, path in changes:
            # Only act on new files, not modifications or deletions
            if change_type != 1:  # 1 = added
                continue

            file = Path(path)
            if not file.is_file():
                continue

            # Brief delay to let the file finish writing
            time.sleep(0.5)

            category = categorize_file(file)
            target = file.parent / category / file.name
            target.parent.mkdir(exist_ok=True)

            # Skip if the file was already moved by another handler
            if not file.exists():
                continue

            # Handle name collisions
            counter = 1
            while target.exists():
                target = target.parent / f"{file.stem}_{counter}{file.suffix}"
                counter += 1

            shutil.move(str(file), str(target))
            print(f"[{time.strftime('%H:%M:%S')}] {file.name} -> {category}/")

The time.sleep(0.5) is a pragmatic hack. When a browser downloads a file, it writes to a temporary filename first (like Unconfirmed 12345.crdownload on Chrome) and renames it to the final name when finished. Without the delay, your script might try to move a file that’s still being written. The 0.5-second pause gives the OS time to finish the rename operation. A more robust approach would check the file’s size twice with a short interval and only proceed when the size stabilizes — but for a personal automation script, the sleep works fine and the code stays readable.

Why use watchfiles instead of polling with time.sleep() in a loop? Polling checks the directory on a fixed interval, which means either wasting CPU by checking too often or missing files by checking too rarely. Watchfiles uses OS-level filesystem event notifications — inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows. When a file is created, the OS tells watchfiles immediately. That means zero CPU usage between events and zero latency when a new file arrives.

If you’re automating a shared directory or a server that processes uploaded files, the watcher approach is the right one. If you just want to clean your Downloads folder once a day, the polling approach with cron is simpler and has fewer moving parts. Choose the tool that matches the scale of your problem.

Cleaning Up Stale Files

The other side of automation is cleanup. Temporary files, old screenshots, cache directories — they accumulate silently until your disk is full. Here’s a script that deletes files older than a specified number of days from a given directory, with a dry-run mode so you can preview what would be deleted before you commit.

from pathlib import Path
import time
import os


def clean_old_files(
    directory: Path,
    days: int = 30,
    dry_run: bool = True,
    extensions: set[str] | None = None,
):
    """
    Delete files older than `days` in `directory`.

    Set dry_run=True to preview without deleting.
    Optionally filter by file extensions.
    """
    now = time.time()
    cutoff = now - (days * 86400)
    deleted = 0
    freed_bytes = 0

    for file in directory.rglob("*"):
        if not file.is_file():
            continue

        if extensions and file.suffix.lower() not in extensions:
            continue

        mtime = file.stat().st_mtime
        if mtime < cutoff:
            size = file.stat().st_size
            if dry_run:
                print(f"Would delete: {file} ({size / 1024:.1f} KB)")
            else:
                file.unlink()
                print(f"Deleted: {file} ({size / 1024:.1f} KB)")

            deleted += 1
            freed_bytes += size

    print(
        f"{'Would delete' if dry_run else 'Deleted'} {deleted} files "
        f"({freed_bytes / 1_048_576:.1f} MB freed)"
    )

The dry_run flag is the most important feature here. Never run a deletion script without previewing first. The rglob("*") recursively walks the directory tree, and file.stat().st_mtime checks the last modification time. The optional extensions filter lets you target specific file types — cleaning up old .zip files in your Downloads while keeping everything else intact.

Running These Scripts Automatically

The scripts are useful on their own, but the whole point of automation is that you don’t have to remember to run them. Here are your options, from simplest to most robust:

On macOS and Linux, cron is the default scheduler. Add a line to your crontab with crontab -e:

# Organize Downloads every hour
0 * * * * /usr/bin/python3 /home/you/scripts/organize_downloads.py

# Clean old files every Sunday at 3 AM
0 3 * * 0 /usr/bin/python3 /home/you/scripts/clean_old_files.py

On Windows, Task Scheduler replaces cron. You can set it up through the GUI or with PowerShell. PowerShell is scriptable:

$action = New-ScheduledTaskAction -Execute "python" -Argument "C:\scripts\organize_downloads.py"
$trigger = New-ScheduledTaskTrigger -Daily -At 3am
Register-ScheduledTask -TaskName "OrganizeDownloads" -Action $action -Trigger $trigger

For the watchfiles-based watcher, you want it running as a background service that starts with your system. On Linux, a systemd user service is the cleanest approach. Create ~/.config/systemd/user/file-watcher.service:

[Unit]
Description=Python File Watcher

[Service]
ExecStart=/usr/bin/python3 /home/you/scripts/watch_downloads.py
Restart=on-failure

[Install]
WantedBy=default.target

Enable it with systemctl --user enable file-watcher.service && systemctl --user start file-watcher.service.

What These Scripts Don’t Handle

File automation scripts work great until they don’t. Here’s what to watch out for before you set one to run unattended for six months and forget about it.

Files that are in use by another process will fail to move. This happens most often with log files that a running application keeps open or with downloads that haven’t finished writing to disk. The script should catch PermissionError and skip the file rather than crashing. A simple try/except around the shutil.move call handles this:

try:
    shutil.move(str(file), str(target))
except PermissionError:
    print(f"Skipped (in use): {file.name}")

Symbolic links and junction points can cause infinite recursion if you’re using rglob for recursive operations. A symlink that points to a parent directory creates a loop, and your script will walk it forever until it hits the filesystem path length limit. Check for symlinks before entering a directory by adding if file.is_symlink(): continue before any recursive traversal. Windows junction points — which look like directories but behave like symlinks — are harder to detect, but pathlib handles them correctly on Python 3.12 and later.

Network drives add latency, temporary disconnections, and permission quirks that local filesystems don’t have. Moving a file across a network mount can take seconds instead of milliseconds, and if the connection drops mid-operation, you get a half-written file in the target directory. Prefer local directories for these scripts. If you must work with network storage, copy first, verify the copy succeeded, then delete the original — never move directly.

Disk space is the silent killer of automation scripts. A shutil.move that works fine with 100MB of files can fill your disk if someone drops a 50GB video into the watched directory and the move destination is on the same partition. The script will copy the entire file before deleting the original, doubling the space used during the operation. If you’re dealing with large files, use os.rename (which is atomic on the same filesystem) and fall back to shutil.move only when rename fails with an OSError.

And the most important rule: never run a file deletion script as root, and never point it at a directory you haven’t reviewed the contents of. The dry_run flag in the cleanup script exists because everyone who has written one of these has a story about accidentally deleting something important. Run with dry_run=True first. Read the output. Confirm the list looks right. Then run for real.

Making These Scripts Your Own

The scripts in this guide are starting points, not finished products. Here’s what most people customize after the first week of running them:

Change the category definitions to match your actual file types. If you work with .blend files or .psd files or whatever proprietary format your industry uses, add those extensions to the dictionary. Remove categories you don’t use — if you’ve never opened a .rar file in your life, take archives out.

Add a log file. A print statement is fine when you’re testing the script interactively, but when it runs at 3 AM via cron, you want a record of what happened. Python’s logging module takes five lines to set up and gives you timestamps, severity levels, and the option to email alerts on errors.

Consider a trash folder instead of permanent deletion. Instead of file.unlink(), move files to ~/.Trash/ or a similar location. Give yourself a week to notice if something important went missing before it’s gone for good. The cleanup script’s dry_run flag helps with this, but a trash folder is an additional safety net that costs nothing.

Python’s standard library gives you almost everything you need for file automation. pathlib for paths, shutil for moves and copies, watchfiles for real-time monitoring, logging for audit trails. The scripts in this guide are under 50 lines each, and combined, they handle the category of computer mess that most people just accept as background noise. Your Downloads folder can go from 400 unsorted files to a clean set of named subdirectories in the time it takes to type python organize_downloads.py. That trade — thirty lines of code for a permanently organized machine — is the kind of deal Python makes better than almost anything else.