Downloads Organizer

A calmer downloads folder. Every file stays on your device.

Preview file moves, build your own rules, and let a local desktop app handle the routine sorting—with history and safe undo.

Download 1.0.0 · How it works · Build and install · Validation

Actual application UI with demonstration files. The tour loops automatically.

Built for everyday downloads

No account, cloud service, telemetry, or administrator privileges are required for normal operation. Python is included in the downloads.

Platform status

Version 1.0.0 is the first stable release. Windows builds are unsigned; macOS builds are ad-hoc signed but lack Developer ID signing and notarization. OS security policies may warn or block installation. Earlier OS versions, real desktop tray/login/reboot behavior on macOS/Linux, and signed installation remain manual validation tasks. See installation guidance.

Get started

Download 1.0.0 for your OS, install it, and open Downloads Organizer. Confirm the folder on first launch, follow the guided tour, and refresh Preview. Nothing moves until you confirm a manual move or enable automatic sorting.

Windows Setup creates a Start-menu shortcut. On macOS, drag the app from the DMG to Applications before launching. On Ubuntu/Debian, install the .deb with the package installer. Portable downloads are also available for Windows/Linux. Full instructions and upgrades.

git clone https://github.com/kashnordeen/downloads-organizer.git
cd downloads-organizer
py -m venv .venv
.venv\Scripts\python.exe -m pip install -e .
.venv\Scripts\pythonw.exe -m organizer

git clone https://github.com/kashnordeen/downloads-organizer.git
cd downloads-organizer
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m organizer

Daily use

1. Choose a folder. The default rules suggest category subfolders.
2. Review Rules. Use Add rule or Edit selected for a guided form. Choose extensions, filename text, and a destination. Reorder rules to set priority, then save.
3. Refresh Preview. Inspect every proposed destination and skipped reason.
4. Organize files. Confirm the manual move, or enable automatic sorting after reviewing your rules.
5. Review History. Select a completed move to undo. If a row says review, select it and choose Move to destination or Leave in Downloads. The app verifies copies before changing either file. A file left in Downloads is skipped on future scans unless it changes.

Switch pages with the sidebar or Alt+1 through Alt+4. Resize table columns or hover over a path to read it in full. Navigation preserves the current preview and automatic monitoring. Editing rules or changing the watched folder pauses sorting and invalidates the preview.

When the window closes

With Keep running in the tray enabled and a usable tray available, closing the window keeps the app running. The tray menu offers Show, Pause/Resume, and Quit. Without a usable tray, closing exits safely.

Quit app finishes the current file before stopping. Automatic mode remains saved, so reopening catches up on downloads created during the stopped period. Start at login is optional and respects operating-system disablement.

Safety and privacy

• Preview never moves files. Manual moves require confirmation and recheck the source against the preview.
• Existing destinations are preserved. Collisions receive numbered names; files are not overwritten.
• Moves are journaled. A verified temporary copy is published using a no-overwrite hard link. A source-only interrupted move becomes retryable on refresh; ambiguous copies stay in History for review.
• Undo checks first. Edited destination files and occupied original paths prevent restoration.
• Only direct regular files are considered. Subfolders, symlinks/junctions, system files, and common partial downloads are skipped.

Readiness uses file age and, in automatic mode, stable metadata observed across scans at least two seconds apart. This cannot prove every download is complete. Avoid files actively modified by other programs: an external writer can race the final source check/removal. Copying requires temporary disk space; filesystems without hard-link support fail safely and retain the source/recovery copy. SHA-256 verifies content, not arbitrary extended metadata.

Settings and SQLite history use Qt's per-user application data location under LocalOrganizer / DownloadsOrganizer. No file data is sent to a server. Interrupted operations may leave hidden .organizer-*.tmp files for manual review.

Inside the app

flowchart LR
    UI[Qt desktop workspace] --> Rules[Ordered rules and preview]
    Folder[Watched folder] --> Scan[Startup scan and readiness checks]
    Scan --> Worker[Automatic worker]
    Rules --> Move[Manual move worker]
    Worker --> Journal[Verified moves and SQLite journal]
    Move --> Journal
    Journal --> Destination[Category folders]
    UI --> Undo[History and safe undo]
    Undo --> Journal

Development and verification

Run from an activated project virtual environment:

python -m unittest discover -s tests -v
python -m compileall -q organizer

The desktop test suite covers rule priority, exclusions, collisions, stale/changed files, recovery, review choices, the Preview Organize button, the guided tour, undo, monitoring, stopped-period catch-up, navigation, tray behavior, startup policy handling, saved settings, and link protection. The desktop workflow runs it and bundled runtime checks on all release targets. Tests use temporary files and offscreen Qt windows, with platform-specific skips. See validation details and remaining gates.

Runtime dependencies are pinned in pyproject.toml; build pins are in packaging/build-requirements.txt. Python's standard library supplies filesystem operations, JSON, SQLite, and tests.

For a bug report, include the OS, Python/app version, reproduction steps, and the displayed error. Use sample files and redact personal paths. Test rule changes against temporary folders before contributing changes that move files.

Code signing policy

Windows downloads are currently unsigned. We are preparing for SignPath Foundation review; approval and signing integration are pending. See our Code signing policy for release responsibilities, privacy, and the remaining activation steps.

License

Project code is licensed under MIT. Dependencies retain their separate licenses. Qt/PySide/Shiboken use the LGPL v3 option; bundles include license texts and upstream attribution files. Releases supply corresponding source archives with checksums and replacement/build instructions. See THIRD_PARTY.md.