File Organizer

A safe, general-purpose local file organizer and file-management CLI that categorizes your files securely and predictably.

Features

  • Safe by Default: Never deletes files automatically. Never silently overwrites files.
  • Dry-run Mode: See what would happen before actually moving anything.
  • Duplicate Handling: Safely handles file collisions (file (1).ext) and skips exact identical duplicates using MD5 hashing.
  • Configurable: Use sensible defaults or provide your own JSON configuration for custom categories.
  • Recursive Mode: Explicitly opt-in to process subdirectories.
  • Hidden/System Files: Safely ignores hidden files (starting with .) and symlinks by default.

Prerequisites

  • Python 3.12 or higher

Installation

You can install this tool using pipx (recommended) or pip:

# Recommended: Install isolated via pipx
pipx install git+https://github.com/techykaif/file_handling.git

# Alternatively, install via pip
pip install git+https://github.com/techykaif/file_handling.git

Usage

Organize a directory:

file-organizer ~/Downloads

Preview changes without moving files:

file-organizer ~/Downloads --dry-run

Organize a directory and its subdirectories:

file-organizer ~/Downloads --recursive

Use a custom configuration:

file-organizer ~/Downloads --config my_categories.json

Skip confirmation prompts (for automation):

file-organizer ~/Downloads --yes

Configuration

By default, files are organized into standard categories (Documents, Images, Videos, Audio, Archives, Code, etc.). You can override these by creating a custom JSON configuration file:

{
  "Photos": [".jpg", ".png", ".heic"],
  "Work": [".pdf", ".docx", ".xlsx"],
  "Music": [".mp3", ".wav"]
}

And passing it via --config:

file-organizer ~/Downloads --config config.json

Safety

File manipulation is potentially destructive, which is why file-organizer implements strong safety defaults:

  • Dry-run (--dry-run): Shows planned changes.
  • No silent overwrites: Filename collisions in the destination are handled gracefully (file (1).txt).
  • No automatic deletion: The tool will not delete any files or directories.
  • No hidden/system file moves: Hidden files and symbolic links are ignored by default.

Development

Clone the repository and install it in development mode:

git clone https://github.com/techykaif/file_handling.git
cd file_handling
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run tests and linting:

pytest
ruff check .

License

This project is licensed under the MIT License - see the LICENSE file for details.

Project links

Data verified by PyPI on Aug 10, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for techykaif from gravatar.com techykaif

Credits

Author: Mohd Kaif Ansari

GitHub Statistics

Data verified by PyPI on Aug 10, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Provides Extra

dev

Tags

file-organizer file-management automation cli python productivity

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kaif_file_organizer-0.1.2.tar.gz (8.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

kaif_file_organizer-0.1.2-py3-none-any.whl (8.0 kB view details)

Uploaded Python 3

File details

Details for the file kaif_file_organizer-0.1.2.tar.gz.

File metadata

  • Download URL: kaif_file_organizer-0.1.2.tar.gz
  • Upload date:
  • Size: 8.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for kaif_file_organizer-0.1.2.tar.gz
Algorithm Hash digest
SHA256 a264dd2bd13099d501b6a6e9abfd775417796e1509b35ae423cf79d9d74f87c4
MD5 510ae1bd2c10ce53a1af067070ad425e
BLAKE2b-256 77112d43467d1d2580266f746111a5d5bd9615c6529feacc802c0729d87cffea

See more details on using hashes here.

Provenance

The following attestation bundles were made for kaif_file_organizer-0.1.2.tar.gz:

Publisher: release.yml on techykaif/file-organizer

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kaif_file_organizer-0.1.2-py3-none-any.whl.

File metadata

File hashes

Hashes for kaif_file_organizer-0.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 d68f13011052d77c70143834159c62b104a2d4fe31ef995718deaba61d1cd835
MD5 ffa8bc7c4813561c89d756c8ab5f07c9
BLAKE2b-256 121a280ce8a774b639e00d860c4a00188e0d1420cbf3644b3b76e0e33fc9021e

See more details on using hashes here.

Provenance

The following attestation bundles were made for kaif_file_organizer-0.1.2-py3-none-any.whl:

Publisher: release.yml on techykaif/file-organizer

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.3

2 files

This release

0.1.2 This release

2 files

0.1.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page