How to Install organize and Create Your First Rule

Updated

Install organize with pip install -U organize-tool on a machine running Python 3.9 or newer, then verify the install with organize --help. From there, run organize new to create a configuration and organize edit to add your first rule. The example below finds PDFs in your Downloads folder and prints a message for each one — a safe way to confirm the tool works before you let it move or rename anything.

Prerequisites

  • Python 3.9 or newer. Install it through your package manager or from python.org.
  • A shell. organize is a command line tool, so you'll run everything from a terminal.
  • No account or license needed. organize is free and open source software, and it works on macOS, Windows, and Linux.

Install organize

The package name on PyPI is organize-tool, not organize:

pip install -U organize-tool

The -U flag also updates an existing installation to the newest version, so the same command works for upgrades.

Verify the installation succeeded:

organize --help

If you see the help output, you're ready to write a rule. If the command isn't found, your Python scripts directory likely isn't on your PATH — check your pip installation notes for that platform.

Create your first rule

Run:

organize new

This creates a configuration file. Then open it for editing:

organize edit

Paste in this rule, which finds PDFs in your Downloads folder and echoes a message for each match:

rules:
  - name: "Find PDFs"
    locations:
      - ~/Downloads
    subfolders: true
    filters:
      - extension: pdf
    actions:
      - echo: "Found PDF!"

Each part does a specific job:

Key Purpose
name A label for the rule, shown in output and logs.
locations The folders organize looks in. ~/Downloads expands to your home Downloads folder.
subfolders When true, the rule also scans folders inside the location.
filters Conditions a file must meet. Here, only files with a .pdf extension match.
actions What happens to matching files. echo prints a message instead of touching the file.

If you have trouble editing the configuration, run organize show --reveal to find where the file lives on disk.

Verify before you act

The echo action is deliberately harmless: it proves your rule matches the files you expect without moving, renaming, or deleting anything. Run the rule and read the output. If the wrong files match, adjust the locations or filters and run it again.

organize is built around this idea — everything can be simulated before your files are touched. Once your rule matches exactly what you want, swap echo for a real action such as moving or renaming.

Where to go next

The same rule structure scales to the tasks organize is commonly used for: sorting and tagging pictures by EXIF data, renaming PDF invoices based on their content, clearing incomplete downloads from ~/Downloads, cleaning up ~/Desktop, and removing duplicate files to free disk space.

Beyond extension, you can filter by extracted text from PDF and DOCX files, and actions can include inline Python or shell commands for cases the built-in actions don't cover. The full documentation on Read the Docs covers configuration, rules, locations, filters, actions, and Docker usage.

A note on versions: v3 is the current release and is described as much faster with fewer bugs, plus new actions, filters, and options. If you're migrating from an older version, follow the migration guide and changelog rather than reusing an old configuration unchanged.