Migrate from Hazel to Sortio: A Rule Translator and Pattern Catalog
A migration guide for long-time Hazel users moving to Sortio. Maps Hazel concepts (rule, condition, action, attribute, custom attribute) to Sortio equivalents, then walks through translating five of the most common Hazel rule patterns: extension-based routing, date-based archival, content-matching on PDFs, source-app routing, and the move-then-script pattern.
In This Guide
The Challenge
Hazel users typically accumulate dozens of rules over years. Some are deterministic and rock-solid: move .dmg files to Installers, archive PDFs over a year old. Others are brittle: read an account number from a bank statement, route by vendor name extracted from an invoice. Migrating to a new tool without losing the rules that work is the real job. A good migration keeps the deterministic stuff intact and uses AI for the brittle cases that have been failing.
Who This Guide Is For
- Long-time Hazel users on Mac evaluating an AI-native alternative
- Mac power users with content-matching rules that keep breaking on PDFs
- Users moving from Mac to Windows or Linux who want their Hazel workflow on the new machine
- Households or small teams with a mix of macOS, Windows, and Linux
- Anyone who has more than 20 Hazel rules and dreads rebuilding them
Step-by-Step Guide
Understand the concept mapping
Hazel has rules, conditions, actions, attributes, and custom attributes. Sortio has rules, AI sorts, and rule sets. A Hazel "rule" maps to a Sortio "rule." A Hazel "condition" (file kind, name pattern, date, contents) maps to a Sortio rule condition with the same primitives. A Hazel "action" (move, rename, tag, run script) maps directly to a Sortio action. Hazel "custom attributes" (extracted values from filename or content) become Sortio token references in a rule template. The one piece without a one-to-one mapping is Hazel's embedded AppleScript actions; Sortio supports shell hooks but not AppleScript, so script-based actions need a small rewrite to use a shell command instead.
Inventory your Hazel rules into three buckets
Open Hazel, take a screenshot of each rule, and sort them into three buckets. Bucket 1 (Keep in Hazel): rules that are working today and you do not want to touch. Bucket 2 (Translate to Sortio rules): deterministic rules that should run the same way in Sortio so you can move off Hazel cleanly. Bucket 3 (Replace with AI sort): brittle content-matching rules, especially PDF rules, that have been failing intermittently. The third bucket is the one Sortio actually changes; the first two are migration mechanics.
Translate extension-based routing (Pattern 1)
Hazel rule: "If extension is dmg, move to Installers." In Sortio, open AI Rule Builder, write "Move all .dmg files to Installers" in plain English, and the builder produces the deterministic rule. This translates one-to-one for every extension-based rule. Sortio runs the rule on watched folders the same way Hazel does. Time per rule: about 30 seconds.
Translate date-based archival (Pattern 2)
Hazel rule: "If date last modified is older than 1 year, move to Archive/2024." In Sortio, use AI Rule Builder with "Move files older than 365 days to Archive/{YYYY} where YYYY is the year the file was last modified." Sortio supports template tokens for date components (year, month, quarter) the same way Hazel's patterns do. Confirm the template renders correctly with a preview before applying.
Translate content matching on PDFs (Pattern 3)
This is the pattern where the migration actually pays off. Hazel rule: "If contents contain regex \bAccount\s+Number:\s*(\d{8})\b, capture the account number, move to Statements/$1." This rule is the one that breaks when OCR drifts. In Sortio, do not write a rule at all; use AI Sort with the prompt "Sort these bank statements into folders by account. The account numbers are 12345678 (Checking), 23456789 (Savings), 34567890 (Joint). The account number is on the first page of each statement." Sortio reads the document and routes accordingly, robust to OCR noise. If you want to promote this to a recurring rule, run AI Rule Builder with the same description.
Translate source-app routing (Pattern 4)
Hazel rule: "If source app is Mail and extension is pdf, move to Email Attachments/PDFs." In Sortio, the equivalent rule uses the source-app condition the same way: "Move PDFs received via Mail to Email Attachments/PDFs." Sortio reads the same macOS extended attributes Hazel does (kMDItemWhereFroms, kMDItemDownloadedDate, kMDItemContentType), so source-app routing translates cleanly.
Translate move-then-script (Pattern 5)
Hazel rule: "Move file, then run AppleScript to update a notes file." Sortio supports a post-action shell hook. Rewrite the AppleScript as a shell script (or wrap the AppleScript with osascript -e) and call it from the Sortio rule. The post-action runs after the move completes. For most automation-style hooks (update an external system, post to a webhook, write a log entry), the shell wrapper takes a few minutes and is more portable than the original AppleScript anyway.
Run a side-by-side test for two weeks
Do not turn off Hazel on day one. Set up Sortio with the migrated rules and an AI sort for the content-matching cases. Point both tools at the same folders. For two weeks, let both run and compare results. After two weeks you will know which Hazel rules to keep, which Sortio rules are working, and which AI sorts have been doing useful work that Hazel could not.
Decide what stays in Hazel for the long term
A small number of Hazel rules are worth keeping in Hazel. AppleScript-heavy automations that have been working for years. Sync-rule setups that depend on iCloud. Custom-attribute rules that extract from filenames and feed Keyboard Maestro macros. These do not need to move. The pragmatic end state for most users is Sortio for content-aware sorting and the rules they want consolidated, plus Hazel for the legacy stuff. The Sortio plus Hazel workflow guide covers how to set up a staging folder that catches files Hazel cannot route and hands them to Sortio.
Example Workflow
1Before
A Mac user has 47 Hazel rules accumulated over five years. About 30 are deterministic (extension, date, source app) and work fine. About 10 do simple renaming and are easy. The remaining 7 are content-matching rules on bank statements, invoices, and tax forms; they break unpredictably, and the user spends an hour every month manually fixing what the rules missed.
2The Prompt
Set up a Sortio inbox folder. AI Rule Builder produces deterministic rules from plain-English descriptions of the 40 stable Hazel rules. AI Sort prompts replace the 7 brittle content-matching rules. The user runs both Hazel and Sortio in parallel for two weeks.3After
After two weeks, the user disables 40 Hazel rules (now in Sortio), keeps 5 Hazel rules that depend on AppleScript or sync, and disables the 7 brittle content-matching rules entirely (replaced by Sortio AI sort). The monthly hour of manual cleanup disappears because Sortio handles the bank statements that Hazel was missing.
Pro Tips
- Migrate one bucket at a time, not all at once. Extension rules first (low risk), then date rules, then source-app rules, then content-matching rules last.
- Keep a text file with your most-used AI Sort prompts. They get better with iteration and you will want to reuse them.
- Hazel's preview mode is excellent for verifying rules before applying. Sortio has the equivalent preview before any move; use it for the first run of each migrated rule.
- The AI Rule Builder is the migration accelerator. Instead of clicking through a rule editor, paste a description of the Hazel rule and let it build the Sortio equivalent.
- For PDFs that have OCR problems, run OCRmyPDF as a pre-step (Sortio can call shell commands the same way Hazel can). Better OCR makes both rule-based and AI sorts more reliable.
- Do not migrate rules that are not working today. If a Hazel rule has been disabled in your config for six months, it is a candidate for an AI Sort prompt instead.
Frequently Asked Questions
How long does a full Hazel to Sortio migration take?
For a user with 30 to 50 rules, the active work is around 2 hours: 1 hour to translate the deterministic rules with AI Rule Builder, and 1 hour to set up AI Sort prompts for the content-matching cases. The two-week parallel-run period is mostly waiting, not work. Most of the time savings come later, when the brittle rules stop breaking.
Can Sortio import a Hazel ruleset directly?
There is no automatic importer. Hazel rules are stored in a proprietary plist format and the rule logic does not always translate cleanly to a different engine. The recommended path is to use Sortio's AI Rule Builder, which takes a plain-English description of each Hazel rule and produces the equivalent Sortio rule. Most rules translate in under a minute.
What happens to my AppleScript-heavy Hazel rules?
Sortio supports post-action shell hooks but not embedded AppleScript. The migration path is to wrap your AppleScript with osascript -e and call it from the Sortio rule as a shell command. For most rules this takes a few minutes. If your AppleScript is deeply integrated with another Mac app (Keyboard Maestro, BetterTouchTool, OmniFocus), you can usually keep that part in Hazel and let Sortio handle the file movement.
Do I have to migrate everything, or can I keep some Hazel rules?
You can absolutely keep both. The Sortio plus Hazel workflow guide covers how to set up a staging folder that catches files Hazel could not route and hands them to Sortio. Many long-time Hazel users end up running both tools indefinitely: Hazel for the rules that have always worked, Sortio for the content-aware cases.
Will my Hazel sync setup survive the migration?
Hazel's iCloud sync is a Hazel-specific feature. Sortio does not directly sync rules across machines, but the rule sets are stored as JSON files that you can share via any sync service (iCloud Drive, Dropbox, a shared repo). For users who built a multi-Mac sync setup in Hazel, the migration path is to keep that sync setup in Hazel for the rules that stay there, and use file-based sync for the Sortio rule sets.
What if Sortio AI sort gets a routing wrong?
Sortio shows a preview before any move and creates a backup of all affected files before applying. If a sort goes wrong, you can either reject the preview or revert the entire sort from the activity log. For routine sorts on watched folders, the recommended setup is to enable preview-required mode for the first month so you can sanity-check each run before files actually move.
Related Glossary Terms
Ready to Implement This Guide?
Sortio can automate much of this workflow with AI-powered file organization. Let Sortio handle the sorting while you focus on your work.
Download Sortio Free