🗂️ mimedy

Tidies up a messy folder by each file's real type, not by its extension.
Range un dossier en désordre selon le vrai type de chaque fichier, pas selon son extension.

mimedy = MIME + tidy: each file's MIME type decides where it belongs.
mimedy = MIME + tidy (ranger) : le type MIME de chaque fichier décide de sa place.

English · Français

🇬🇧 English

Contents: Why · Features · Installation · Usage · Configuration · Ignored files · How is a file classified · Project structure · Development · Roadmap · License

Why?

A Downloads folder always ends up looking the same: PDFs, screenshots, archives, a .json exported at some point, a file with no extension that nobody remembers…

Most organizing tools trust file extensions. But an extension can lie, be missing, or simply be wrong. mimedy uses Magika, Google's deep learning model that identifies a file from its content, to decide where it belongs.

$ mimedy ~/Downloads
[INFO] Loaded config from /Users/me/.config/mimedy/config.yaml
[INFO] Organizing /Users/me/Downloads
[INFO] 'export.csv' → Data/
[INFO] 'holidays.jpg' → Photos/
[INFO] 'invoice' → PDF/
[INFO] 'report.pdf' → PDF/report (1).pdf
[INFO] 'script.py' → Python/
[WARNING] Skipped 'locked.txt': Magika could not read the file (permission_error)
[INFO] 5 files to move into 4 folders, 1 skipped, 0 ignored
Move 5 files? [y/N]: y
[INFO] Done: 5 moved, 0 failed

Features

• 🧠 Content-based detection: Magika recognizes over 200 file types, even when renamed or missing an extension.
• 🔒 100% local: the AI model ships with the tool and runs on your machine. No network connection, no file or data is ever sent anywhere.
• 🪜 Cascading rules: hidden files, large files, extensions, MIME types, then the Magika group as a fallback.
• 📋 Plan, then confirm: every move is shown before it happens, and nothing moves without your approval. --dry-run stops at the plan.
• 🧯 Robust: an unreadable or locked file is reported and skipped, without stopping the run.
• 🙈 System files ignored: .DS_Store, Thumbs.db… stay where they are, and you can add your own patterns (*.part).
• 🛡️ Never overwrites: if photo.jpg already exists, the new file becomes photo (1).jpg.
• 🐛 --verbose mode: shows which rule decided each file's destination.
• ⚙️ Simple YAML configuration, entirely optional.

Installation

mimedy is published on PyPI and requires Python 3.10+. The easiest way is to install it as an isolated tool with uv or pipx:

uv tool install mimedy     # or: pipx install mimedy

To try it without installing anything:

uvx mimedy ~/Downloads --dry-run

Usage

💡 mimedy always shows the full plan and asks for confirmation before moving anything.

# Show the plan, then confirm
mimedy ~/Downloads

# Only show the plan
mimedy ~/Downloads --dry-run

# No confirmation, e.g. in a script
mimedy ~/Downloads --yes --config my-config.yaml

# Understand why a file goes where it goes
mimedy ~/Downloads --dry-run --verbose

Only files directly inside the folder are processed. Existing subfolders are left untouched, so the tool can safely be run again.

Configuration

Without --config, mimedy reads your personal configuration file, if it exists:

If it doesn't exist, the defaults are used. A file passed with --config, however, must exist. mimedy --help shows the exact location on your machine.

To get started, create a commented example config, then adapt it:

mimedy --init-config
# Created config file: /Users/me/.config/mimedy/config.yaml

ignore_system_files: true   # leave .DS_Store, Thumbs.db… in place
ignore:                     # extra patterns, case-insensitive
  - "*.part"
  - "*.crdownload"

hidden: "Hidden"            # files starting with '.'

large_files:
  threshold_mb: 500         # decimal MB, like Finder or Explorer
  target_dir: "Large"

extensions:                 # exact extension match
  .blend: "Blender"
  .csv: "Data"

mimetypes:                  # MIME type detected by Magika
  application/pdf: "PDF"
  image/jpeg: "Photos"

Every key is optional: missing ones fall back to their default value. Destinations may include subfolders ("Code/Python"). See config.example.yaml, the file copied by --init-config, for a complete, commented example.

Ignored files

Some files are never moved. They don't appear in the plan, don't count as failures, and --verbose lists them with the reason.

System files. They are created by the system or the file manager: moving them is useless (they are recreated) or breaks what they describe. Names are compared ignoring case.

To organize them like any other file, turn this rule off:

ignore_system_files: false

Your own patterns. The ignore list adds patterns, matched against the whole file name and ignoring case: * stands for any run of characters, ? for a single character, [abc] for one of the listed characters.

ignore:
  - "*.part"          # download in progress (Firefox)
  - "*.crdownload"    # download in progress (Chrome)
  - "~$*"             # lock file of an open Office document

These patterns come on top of the system files: no need to repeat them.

How is a file classified?

First of all, ignored files stay in place.

The other files go through these rules, in this order; the first match wins:

Rules 1 to 3 don't read file contents, so they are instant. Magika only runs when they aren't enough.

Project structure

mimedy/
├── pyproject.toml
├── src/mimedy/
│   ├── main.py              # CLI entry point (Typer)
│   ├── config.py            # Configuration loading and validation
│   ├── config.example.yaml  # Commented example configuration
│   ├── organizer.py         # Classification rules, planning and moves
│   └── errors.py            # Project exceptions
└── tests/                   # pytest tests (configuration, rules, plan, CLI)

Development

Code is checked by Ruff (linting and formatting) on every commit, and tested with pytest. Continuous integration runs both on every push, on Python 3.10 to 3.14.

git clone https://github.com/ochapeau/mimedy.git
cd mimedy
uv sync                     # create the development environment
uv run pre-commit install   # automatic checks on every commit
uv run pytest               # run the tests
uv run mimedy --help        # run the development version

Roadmap

• Typed, validated configuration
• Global configuration in ~/.config/mimedy/
• Automated tests and continuous integration
• Publish on PyPI (uv tool install mimedy)
• Ignore system files (.DS_Store, .localized, Thumbs.db, desktop.ini…), with an option to organize them anyway
• File patterns to ignore (downloads in progress: *.part, *.crdownload…)
• Undo the last run (--undo)
• Optional terminal interface (TUI)

License

Released under the MIT License. See LICENSE.

🇫🇷 Français

Sommaire : Pourquoi · Fonctionnalités · Installation · Utilisation · Configuration · Fichiers ignorés · Comment un fichier est-il classé · Structure du projet · Développement · Feuille de route · Licence

Pourquoi ?

Un dossier Téléchargements finit toujours par ressembler à ça : des PDF, des captures d'écran, des archives, un .json exporté un jour, un fichier sans extension dont personne ne se souvient…

La plupart des outils de rangement se fient à l'extension. Or une extension peut mentir, manquer ou être fausse. mimedy utilise Magika, le modèle de deep learning de Google qui identifie un fichier à partir de son contenu, pour décider où il doit aller.

$ mimedy ~/Downloads
[INFO] Loaded config from /Users/me/.config/mimedy/config.yaml
[INFO] Organizing /Users/me/Downloads
[INFO] 'export.csv' → Data/
[INFO] 'holidays.jpg' → Photos/
[INFO] 'invoice' → PDF/
[INFO] 'report.pdf' → PDF/report (1).pdf
[INFO] 'script.py' → Python/
[WARNING] Skipped 'locked.txt': Magika could not read the file (permission_error)
[INFO] 5 files to move into 4 folders, 1 skipped, 0 ignored
Move 5 files? [y/N]: y
[INFO] Done: 5 moved, 0 failed

Fonctionnalités

• 🧠 Détection par le contenu : Magika reconnaît plus de 200 types de fichiers, même renommés ou sans extension.
• 🔒 100 % local : le modèle d'IA est livré avec l'outil et tourne sur votre machine. Aucune connexion réseau, aucun fichier ni aucune donnée n'est envoyé où que ce soit.
• 🪜 Règles en cascade : fichiers cachés, fichiers volumineux, extensions, types MIME, puis le groupe Magika en dernier recours.
• 📋 Plan puis confirmation : tous les déplacements sont affichés avant d'être effectués, et rien ne bouge sans votre accord. --dry-run s'arrête au plan.
• 🧯 Robuste : un fichier illisible ou verrouillé est signalé et ignoré, sans interrompre le rangement.
• 🙈 Fichiers système ignorés : .DS_Store, Thumbs.db… restent à leur place, et vous pouvez ajouter vos propres motifs (*.part).
• 🛡️ Aucun écrasement : si photo.jpg existe déjà, le nouveau fichier devient photo (1).jpg.
• 🐛 Mode --verbose : indique pour chaque fichier la règle qui a décidé de sa destination.
• ⚙️ Configuration YAML simple, entièrement facultative.

Installation

mimedy est publié sur PyPI et nécessite Python 3.10+. Le plus simple est de l'installer comme outil isolé avec uv ou pipx :

uv tool install mimedy     # ou : pipx install mimedy

Pour l'essayer sans rien installer :

uvx mimedy ~/Downloads --dry-run

Utilisation

💡 mimedy affiche toujours le plan complet et demande confirmation avant de déplacer quoi que ce soit.

# Afficher le plan, puis confirmer
mimedy ~/Downloads

# Afficher le plan seulement
mimedy ~/Downloads --dry-run

# Sans confirmation, par exemple dans un script
mimedy ~/Downloads --yes --config my-config.yaml

# Comprendre pourquoi un fichier va à tel endroit
mimedy ~/Downloads --dry-run --verbose

Seuls les fichiers situés directement dans le dossier sont traités. Les sous-dossiers existants ne sont pas touchés, ce qui permet de relancer l'outil sans risque.

Configuration

Sans --config, mimedy lit le fichier de configuration personnel, s'il existe :

S'il n'existe pas, les valeurs par défaut sont utilisées. Un fichier passé avec --config doit en revanche exister. mimedy --help affiche l'emplacement exact sur votre machine.

Pour démarrer, créez une configuration d'exemple commentée, puis adaptez-la :

mimedy --init-config
# Created config file: /Users/me/.config/mimedy/config.yaml

ignore_system_files: true   # laisser .DS_Store, Thumbs.db… en place
ignore:                     # motifs en plus, sans tenir compte de la casse
  - "*.part"
  - "*.crdownload"

hidden: "Hidden"            # fichiers commençant par '.'

large_files:
  threshold_mb: 500         # en Mo décimaux, comme le Finder ou l'Explorateur
  target_dir: "Large"

extensions:                 # correspondance exacte sur l'extension
  .blend: "Blender"
  .csv: "Data"

mimetypes:                  # type MIME détecté par Magika
  application/pdf: "PDF"
  image/jpeg: "Photos"

Toutes les clés sont facultatives : celles qui manquent reprennent leur valeur par défaut. Les destinations peuvent contenir des sous-dossiers ("Code/Python"). config.example.yaml, le fichier copié par --init-config, contient un exemple complet et commenté.

Fichiers ignorés

Certains fichiers ne sont jamais déplacés. Ils n'apparaissent pas dans le plan, ne comptent pas comme des erreurs, et --verbose les liste avec la raison.

Fichiers système. Ils sont créés par le système ou le gestionnaire de fichiers : les déplacer ne sert à rien (ils sont recréés) ou casse ce qu'ils décrivent. Les noms sont comparés sans tenir compte de la casse.

Pour les ranger comme les autres fichiers, désactivez cette règle :

ignore_system_files: false

Vos propres motifs. La liste ignore ajoute des motifs, comparés au nom complet du fichier sans tenir compte de la casse : * remplace n'importe quelle suite de caractères, ? un seul caractère, [abc] un caractère parmi ceux indiqués.

ignore:
  - "*.part"          # téléchargement en cours (Firefox)
  - "*.crdownload"    # téléchargement en cours (Chrome)
  - "~$*"             # fichier de verrouillage d'un document Office ouvert

Ces motifs s'ajoutent aux fichiers système : inutile de les répéter.

Comment un fichier est-il classé ?

Avant tout, les fichiers ignorés restent en place.

Les autres fichiers passent par ces règles, dans cet ordre ; la première qui correspond l'emporte :

Les règles 1 à 3 ne lisent pas le contenu des fichiers : elles sont instantanées. Magika n'est appelé que si elles ne suffisent pas.

Structure du projet

mimedy/
├── pyproject.toml
├── src/mimedy/
│   ├── main.py              # Point d'entrée de la CLI (Typer)
│   ├── config.py            # Chargement et validation de la configuration
│   ├── config.example.yaml  # Configuration d'exemple commentée
│   ├── organizer.py         # Règles de classement, planification et déplacements
│   └── errors.py            # Exceptions du projet
└── tests/                   # Tests pytest (configuration, règles, plan, CLI)

Développement

Le code est vérifié par Ruff (lint et formatage) à chaque commit, et testé avec pytest. L'intégration continue lance les deux à chaque push, sur Python 3.10 à 3.14.

git clone https://github.com/ochapeau/mimedy.git
cd mimedy
uv sync                     # crée l'environnement de développement
uv run pre-commit install   # vérifications automatiques à chaque commit
uv run pytest               # lancer les tests
uv run mimedy --help        # lancer la version en cours de développement

Feuille de route

• Configuration typée et validée
• Configuration globale dans ~/.config/mimedy/
• Tests automatisés et intégration continue
• Publication sur PyPI (uv tool install mimedy)
• Ignorer les fichiers système (.DS_Store, .localized, Thumbs.db, desktop.ini…), avec une option pour les ranger quand même
• Motifs de fichiers à ignorer (téléchargements en cours : *.part, *.crdownload…)
• Annuler le dernier rangement (--undo)
• Interface en terminal (TUI), en option

Licence

Distribué sous licence MIT. Voir LICENSE.