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
- Download Python from the official website.
⚠️ 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
- Click the green "<> Code" button at the top of this page.
- Select "Download ZIP".
- Extract the downloaded ZIP file to any folder on your computer (e.g., your Desktop).
Step 3: First-time Setup
- Open the extracted folder.
- 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
- Simply double-click
gui.pyw. - The application will open cleanly without any background consoles. You can create a desktop shortcut of
gui.pywfor 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.
- 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.txtpython gui.pyOn 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/ENselector 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.
# 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. |
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 raiseValueErrorto avoid accidental exclusions.simulate: whenTrue, 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.
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_HISTORYenvironment 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}")From the project folder:
python -m pip install pyinstaller
python -m PyInstaller --noconfirm --onefile --windowed --name "FileOrganizer" --collect-all customtkinter gui.pyThe 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.
-
Recursive scan: walks the root and its subfolders. It does not follow symbolic links and never enters excluded folders.
-
Categories: each file is moved into a top-level folder inside the root based on its extension:
Folder Extensions (summary) Documentospdf, doc/docx, odt, rtf, txt, md, epub... Imágenesjpg, jpeg, png, gif, webp, svg, heic, raw... Vídeosmp4, mkv, avi, mov, webm... Audiomp3, wav, flac, m4a, ogg... Comprimidoszip, rar, 7z, tar, gz, iso... Hojas_de_cálculoxls/xlsx, ods, csv, tsv... Presentacionesppt/pptx, odp, key... Códigopy, js, ts, html, css, java, c, sql... Datosjson, xml, yaml, sqlite, parquet... Configuraciónenv, ini, cfg, toml... Fuentesttf, otf, woff, woff2... Ejecutablesexe, msi, apk, dmg, deb... Diseñopsd, ai, xcf, fig, blend... The complete list is in
CATEGORIES(organizer.py); adding an extension there is enough. -
Unknown extensions:
.xyzis moved toOtros_XYZ. A file without an extension goes toOtros_SIN_EXTENSION. -
Name conflicts: if the destination already exists, a numeric suffix is added:
file.pdf,file_1.pdf,file_2.pdf... -
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.
-
Idempotence: running the script twice in a row moves nothing the second time; files already in their category are left untouched.
python -m unittest discover -s tests -v