A small, safe, open-source CLI that sorts files into category folders.
File Organizer is deliberately conservative: it organizes one directory, ignores subdirectories unless asked to recurse, skips hidden files, and never silently overwrites an existing file.
- Python 3.11 or newer
Clone the repository and install it locally:
git clone https://github.com/vanox03/file-organizer.git
cd file-organizer
python -m pip install .For development:
python -m pip install -e ".[dev]"Preview the default organization of the current directory:
file-organizer organize --dry-runOrganize a selected directory:
file-organizer organize ~/DownloadsInclude files inside subdirectories:
file-organizer organize ~/Downloads --recursiveUse custom rules:
file-organizer organize ~/Downloads --config examples/organizer.toml --dry-runThe built-in categories are Images, Documents, Audio, Video, Archives,
and Other.
Rules use TOML. Extensions may be written with or without a leading dot.
[rules]
Pictures = ["jpg", "jpeg", "png"]
Writing = ["md", "pdf", "txt"]
[settings]
uncategorized = "Misc"See examples/organizer.toml for a complete example.
--dry-runpreviews actions without changing files.- Existing destination files are never overwritten.
- Name collisions become
filename (1).ext,filename (2).ext, and so on. - Hidden files and files already inside category folders are skipped.
- Invalid configurations stop the command before any file is moved.
Always review a dry run before organizing important directories.
Contributions are welcome. Read CONTRIBUTING.md before
opening a pull request.
Contributors:
Licensed under the MIT License.