Skip to content

About

Automate your folder cleanup with this lightweight, local Python tool

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

File organizer by extension

📥 How to Install and Run (No technical skills required)

Since this application runs locally and avoids compiled .exe files to prevent antivirus false positives, you just need Python installed on your computer.

Step 1: Install Python

  1. Download Python from the official website.
  2. ⚠️ CRITICAL: When running the Python installer, check the box at the bottom that says "Add python.exe to PATH" before clicking "Install Now".

Step 2: Download the Application

  1. Click the green "<> Code" button at the top of this page.
  2. Select "Download ZIP".
  3. Extract the downloaded ZIP file to any folder on your computer (e.g., your Desktop).

Step 3: First-time Setup

  1. Open the extracted folder.
  2. Double-click the file named Install_Dependencies.bat. A black window will appear briefly to download the visual interface components. Press any key when it finishes.

Step 4: Run the App

  1. Simply double-click gui.pyw.
  2. The application will open cleanly without any background consoles. You can create a desktop shortcut of gui.pyw for quick access.

Python script that organizes a folder and all of its subfolders into categories based on each file's extension. It resolves name conflicts and removes the folders that become empty. It also includes a modern graphical interface built with customtkinter.

Requirements

  • Python 3.9 or later.
  • For the graphical interface, customtkinter (the rest uses only the standard library: pathlib, shutil, argparse, dataclasses).
python -m pip install -r requirements.txt

Graphical interface

python gui.py

On Windows you can also double-click run_gui.bat.

The window provides:

  • Select folder to organize using a system dialog.
  • Add exclusions: choose subfolders inside the root that must not be analyzed or modified. Each exclusion is shown in a list with its Remove button. If you change the root folder, exclusions are cleared to avoid keeping paths that no longer apply.
  • Simulation mode: shows what would happen without moving or deleting anything.
  • Switch between light and dark themes with the toggle in the upper-right corner. Both themes keep the soft interface palette.
  • Switch between Spanish and English with the ES / EN selector at the top. Interface text updates instantly.
  • Organize Files: asks for confirmation and runs the organization in a background thread, so the window keeps responding. The detailed result appears in the Log panel.
  • Undo last organization: returns the files from the last session to their original locations (see below).

Communication between the worker thread and the interface uses a queue.Queue polled with after, so only the main thread touches Tk widgets.

Quick start (command line)

# Preview what would happen without changing anything
python organizer.py "C:\Users\You\Downloads" --simulate

# Organize for real
python organizer.py "C:\Users\You\Downloads"

# Exclude one or more folders (absolute paths, repeatable)
python organizer.py "C:\Users\You\Downloads" `
    --exclude "C:\Users\You\Downloads\Projects" `
    --exclude "C:\Users\You\Downloads\Backups"

Options:

Option Description
root Folder to organize (defaults to the current directory).
-e, --exclude PATH Absolute folder that is not analyzed or modified. Can be repeated.
-n, --simulate Show the moves and folders to delete without touching anything.

Use as a module

from pathlib import Path
from organizer import organize_directory

summary = organize_directory(
    r"C:\Users\You\Downloads",
    excluded_folders=[
        Path(r"C:\Users\You\Downloads\Projects"),
        Path(r"C:\Users\You\Downloads\Backups"),
    ],
)

for source, destination in summary.moved:
    print(f"{source} -> {destination}")

print(f"Moved: {len(summary.moved)}")
print(f"Deleted folders: {len(summary.deleted_folders)}")
for path, error in summary.errors:
    print(f"Error in {path}: {error}")

Parameters of organize_directory:

  • root: root folder to organize.
  • excluded_folders: iterable of absolute paths that must not be analyzed or modified, including their contents. Relative paths raise ValueError to avoid accidental exclusions.
  • simulate: when True, nothing is moved or deleted and the function returns what would have happened.
  • skip_files: specific files that must be ignored.

It returns a Summary with moved, deleted_folders, unchanged, errors, and simulated.

Undo the last organization

Every real organization (from the GUI or the command line) stores a JSON file with the mapping original path -> new path for every moved file:

  • Windows: %LOCALAPPDATA%\FileOrganizer\last_organization.json
  • Other systems: ~/.file_organizer/last_organization.json
  • Override it with the ORGANIZER_HISTORY environment variable.

The GUI Undo last organization button reads that file and returns the files to their original locations:

  • Occupied paths are never overwritten: if the original destination already exists, that file stays where it is and the move remains in the history.
  • Folders that become empty while undoing are deleted.
  • If some moves fail, they remain in the JSON file so they can be retried; if every move is restored, the JSON file is deleted.
  • Simulations do not create or modify the history.

It is also available as an API:

from history import undo_last

result = undo_last()
print(f"Restored: {len(result.restored)}")
for movement, reason in result.failed:
    print(f"Could not restore {movement.source}: {reason}")

Build an executable with PyInstaller

From the project folder:

python -m pip install pyinstaller
python -m PyInstaller --noconfirm --onefile --windowed --name "FileOrganizer" --collect-all customtkinter gui.py

The result is written to dist\FileOrganizer.exe, a single file with no console window. --collect-all customtkinter includes the library themes and resources. Add --icon="path\to\icon.ico" if you want an icon.

The history is stored under %LOCALAPPDATA%, not in the temporary folder PyInstaller uses when starting the .exe, so Undo keeps working between runs.

Behavior

  1. Recursive scan: walks the root and its subfolders. It does not follow symbolic links and never enters excluded folders.

  2. Categories: each file is moved into a top-level folder inside the root based on its extension:

    Folder Extensions (summary)
    Documentos pdf, doc/docx, odt, rtf, txt, md, epub...
    Imágenes jpg, jpeg, png, gif, webp, svg, heic, raw...
    Vídeos mp4, mkv, avi, mov, webm...
    Audio mp3, wav, flac, m4a, ogg...
    Comprimidos zip, rar, 7z, tar, gz, iso...
    Hojas_de_cálculo xls/xlsx, ods, csv, tsv...
    Presentaciones ppt/pptx, odp, key...
    Código py, js, ts, html, css, java, c, sql...
    Datos json, xml, yaml, sqlite, parquet...
    Configuración env, ini, cfg, toml...
    Fuentes ttf, otf, woff, woff2...
    Ejecutables exe, msi, apk, dmg, deb...
    Diseño psd, ai, xcf, fig, blend...

    The complete list is in CATEGORIES (organizer.py); adding an extension there is enough.

  3. Unknown extensions: .xyz is moved to Otros_XYZ. A file without an extension goes to Otros_SIN_EXTENSION.

  4. Name conflicts: if the destination already exists, a numeric suffix is added: file.pdf, file_1.pdf, file_2.pdf...

  5. Empty folders: when finished, all empty folders are removed from the deepest level upwards. The root is never removed, and excluded folders are kept even when empty.

  6. Idempotence: running the script twice in a row moves nothing the second time; files already in their category are left untouched.

Tests

python -m unittest discover -s tests -v

About

Automate your folder cleanup with this lightweight, local Python tool

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages