PyStou

Welcome to PyStou – your ultimate toolkit for keeping your filesystem tidy and organized! Whether you're a developer drowning in duplicate folders or someone who loves archiving files but hates the clutter, PyStou is here to rescue you from chaos with style and efficiency.

PyStou is proudly developed by the International Consortium of Investigative Journalists (ICIJ), aiming to empower users with tools to manage and maintain large amounts of files.

Install

pipx install pystou      # isolated environment, recommended
uv tool install pystou   # https://docs.astral.sh/uv/
pip install pystou

Requires Python 3.9+. typer and rich are installed automatically.

Some archive formats need an external tool. Run pystou doctor to check which are present:

From source:

git clone https://github.com/ICIJ/pystou.git
cd pystou
make install

Quick start

pystou stats  ~/Downloads -r            # what is in here?
pystou dedup  ~/Downloads -r            # prompt per duplicate group
pystou extract ~/Downloads -r --action extract
pystou cleanup ~/Downloads -r           # drop .DS_Store, Thumbs.db, ...
pystou restore ~/Downloads --all        # undo the above

Commands

Every command takes an optional directory (default: current) and --help.

Reversible by default

cleanup, dedup, and extract never delete: they move items into a .pystou-trash/ directory next to the target. Use pystou restore to undo and pystou trash purge to reclaim the space. pystou trash purge is the only command that truly deletes data.

Pass --hard-delete to delete immediately instead.

Where PyStou writes

Logs and index databases follow the XDG Base Directory specification, so no command litters the directory you run it from:

Each scanned tree gets its own index file, named after the target and a hash of its absolute path, so a run on /data is never offered the index built for /photos. Indexes are a cache: deleting them only costs a rescan.

Quarantined files are the exception and stay in .pystou-trash/ next to the target, because quarantining has to be a same-filesystem move to be atomic. Use --trash-dir to place it elsewhere on that filesystem.

Global options

These go before the subcommand name.

pystou --no-color dedup /data -r
pystou --quiet extract /data -r --action extract

Shared options

Command reference

dedup

Identify duplicate directories and delete or merge them.

pystou dedup [directory] [options]

pystou dedup /data -r                    # prompt per group
pystou dedup /data -r --action delete    # keep one copy of each
pystou dedup /data -r --action merge     # merge contents, then quarantine

extract

Extract archives and optionally clean up the sources.

pystou extract [directory] [options]

Each archive is extracted into its own directory beside it, named after the archive (photos.zip -> photos/). If that name is taken, a numbered one is used (photos (1)/), so extracting never overwrites existing files.

Supported formats: .zip, .tar, .tar.gz, .tgz, .tar.bz2, .tbz, .gz, .bz2, .zst, .tar.zst, .tzst, .pst, .ost, and split ZIP (.z01, .z02, ... detected from the main .zip).

pystou extract /data -r --action extract --remove-archives
pystou extract /data -r --action extract -p 4 --nested
pystou extract /data -r --action extract --type zip --type pst

Outlook PST/OST: readpst sometimes exits with an error, most often on a modern Office 365 .ost cache, after already extracting most of the mail. By default PyStou treats that as a failure: the partial output is discarded and the archive is left in place. --tolerant keeps whatever messages were written and reports a warning. The recovered mail may be incomplete, which is why it is opt-in.

cleanup

Remove junk files created by operating systems and applications.

pystou cleanup [directory] [options]

Removed by default:

• macOS: .DS_Store, ._.DS_Store, ._*, __MACOSX, .AppleDouble, .Spotlight-V100, .Trashes, .fseventsd, .TemporaryItems, .LSOverride
• Windows: Thumbs.db, ehthumbs.db, ehthumbs_vista.db, desktop.ini

pystou cleanup /data -r --list-only
pystou cleanup /data -r --include ".gitkeep" --include ".keep"

identify

Detect file types and flag mismatched extensions or encrypted archives.

pystou identify [directory] [options]

pystou identify /data -r --check encrypted
pystou identify /data -r --check mismatch --extensions ".zip,.pdf,.docx"

normalize

Renames files and directories whose names are not valid, portable UTF-8, so they can be synced to S3. Every rename is recorded in a JSONL manifest that a downstream job can replay against a search index.

pystou normalize ~/data -r --dry-run     # preview
pystou normalize ~/data -r               # rename, writing a manifest
pystou normalize ~/data -r --rule utf8   # only the S3 blocker
pystou normalize ~/data -r --no-manifest # rename without recording anything
pystou normalize ~/data -r -s            # print counts, not one row per path
pystou normalize --undo 20260819T101500Z-3f2a

All rules run by default. --rule is repeatable.

Manifests are written to $XDG_STATE_HOME/pystou/renames (override with --manifest-dir). Replay entries in file order: each file entry is an exact path swap, and each dir entry is a prefix rewrite over everything below it.

-s replaces the per-path table with a count of what was renamed, or restored when combined with --undo. On a tree with millions of bad names the per-path table is not just unreadable, it is held in memory before it is printed, so -s skips building it at all. Failures are still reported individually: they are errors, not progress. Use -q to silence the status lines as well.

--no-manifest skips the record entirely, for trees nothing has indexed. Note that --undo replays a manifest, so a run without one cannot be reversed; pystou says so after the run rather than leaving you to find out later. It is rejected together with --manifest-dir, which would contradict it.

stats

Report on files and directories.

pystou stats [directory] [options]

pystou stats /data -r --by-size --top 20
pystou stats /data -r --json

empty

Find and remove empty directories.

pystou empty [directory] [options]

pystou empty /data -r --list-only
pystou empty /data -r --include-hidden

restore

Move quarantined items back to their original locations.

pystou restore [directory] [options]

pystou restore /data --run 20260613T142501Z-9f3a
pystou restore /data --all
pystou restore /data --path /data/old-file.zip

Restore never overwrites an occupied path. If the original destination exists, the item stays in the trash and is reported as skipped.

trash

pystou trash list  [directory] [--json]
pystou trash purge [directory] [options]

list shows every quarantine run with its item count and reclaimable space. purge permanently deletes; there is no undo.

pystou trash list /data
pystou trash purge /data --older-than 30

doctor

Check that readpst, zstd, and 7z are installed and on your PATH.

pystou doctor [--json]

Migrating from 0.x

0.3.0 replaced the argparse CLI of 0.2.x with Typer.

Behavior changes:

• cleanup, dedup, and extract quarantine instead of deleting. --hard-delete restores the old behavior.
• New commands: pystou restore, pystou trash list, pystou trash purge, pystou doctor.
• pystou --install-completion enables shell tab-completion.

Development

make install    # sync the environment with dev extras
make test
make lint
make typecheck

Archive extraction tests need readpst, zstd, and 7z on your PATH.

License

MIT.