Hazel: what it does and where it breaks down

Hazel is a rules engine for folders on macOS. It watches locations that collect files and applies rules to whatever lands there. That description is accurate and still leaves the important question open, which is where the automation stops and manual work resumes. Every tool in this category has that line. Finding it before installing is the difference between a Downloads folder that stays empty on its own and a set of rules that gets abandoned after a week.

The model is two things, and nothing else

Hazel asks for exactly two inputs. A folder to watch, and rules to run against what appears in it. A rule has conditions, which describe what to look for, and actions, which describe what happens when the conditions match. The structure is the same one Apple Mail uses for message rules.

Out of the box, only the Downloads folder is registered, and adding a folder on its own does nothing at all until a rule exists. The vendor documentation is specific about which folders repay the effort: browser download locations, the folder where a mail client drops attachments, a shared cloud folder. What these have in common is that files arrive in them without anyone deciding to put them there. A folder that has already been organised and rarely changes gains nothing from being watched.

This matters for setup order. The common mistake is to add six folders at once, write thirty rules, and then spend a week working out which rule fired on which file. A single folder with two rules that run correctly is worth more, because the feedback loop is short enough to debug.

There is a shortcut for adding the usual suspects. Hazel offers app folders, a list that picks up the download location configured in Safari, Mail, Firefox, and Transmission, including cases where the location has been moved away from the default. The Transmission entry carries a warning that generalises well beyond that one app: keep incomplete downloads in a separate folder from finished ones, so that rules never run against a file that is still being written. The same hazard appears with cloud sync folders and with any application that writes its output slowly. Before adding a folder, the question to answer is whether files appear there finished or in progress.

The folders that repay nothing are the stable ones. An archive of past projects sorted by year receives no new files, so no rule ever fires against it. Smart Folders can be watched, with what the documentation calls minor limitations, which makes them a reasonable target for reporting but a poor one for actions that move things.

Rules can be combined with any, all, or none logic, and conditions can be nested. That is enough expressive power to describe most filing decisions that a person could describe out loud in one sentence. It is not enough to describe a decision that depends on knowing what a project is about.

Twenty years of one developer, and one large break in the middle

Hazel first shipped in September 2006. Noodlesoft, the company behind it, marked the twentieth anniversary on 4 September 2026 with a weekend sale at 35 percent off, including upgrades, and a note telling buyers to use the web store rather than the in-app one because the discount might not appear there.

The break worth knowing about happened in 2020. Through version 4, Hazel shipped as a preference pane that installed into System Preferences. Version 5, released in November 2020, moved to a standalone application. The developer explained the reason on the company blog: macOS Catalina broke preference panes badly, no improvement followed, and preference panes looked like a development dead end.

That history has a practical consequence. Search results, forum posts, and tutorials written before 2021 describe an interface that no longer exists. Instructions that begin by opening System Preferences are for version 4 or earlier and will not match what is on screen now.

Hazel is not a subscription. A license unlocks the major version purchased, with free upgrades inside that version, and it keeps working when a new major version appears. Hazel 6 costs 42 US dollars for a single user and 65 dollars for a family pack covering up to five people in one household. Upgrading from any earlier version costs 20 dollars regardless of license type.

What can be matched, and what can be done

The range of conditions is where this tool earns its reputation. The published examples cover name and size, creation and modification dates, the text content of a document, Finder tags and comments, the number of items inside a subfolder, and normally hidden Spotlight metadata such as image resolution or the composer field on an audio file.

Actions have similar range. Move, copy, sort into a subfolder, rename, archive or unarchive, change tags and comments, import into Photos or Music, upload to a server, run a Shortcut, run AppleScript or JavaScript, run an Automator workflow.

Condition type	Example from the documentation	Typical use
Name or size	Size is greater than 100 MB	Catching large downloads before they pile up
Date	Date Created is in the last week	Retiring old documents from an active folder
Document contents	Contents contain a word followed by a three digit number	Separating invoices from quotes
Tags and comments	Tags contain Work	Using a manual mark as a trigger
Media metadata	Resolution width is less than 300	Sorting screenshots away from photographs
Item count	Sub-file/folder Count is less than 5	Cleaning up near empty folders

The pattern behind the list is worth stating plainly. If the deciding fact can be read off the file by a machine, a rule can express it. If the deciding fact lives in someone's head, such as whether a document belongs to the project that is currently active, no condition covers it. That boundary explains most of the frustration people report after a month of use.

What Hazel 6 added

Two changes in the current version are large enough to affect whether the tool fits a given workflow.

The first is reading. Hazel 6 performs on-the-fly text recognition, so PDFs that were never run through OCR and plain image files can be matched on their text content. Encrypted PDFs can be read if a password is supplied, and those passwords are stored in the keychain. For anyone whose incoming paperwork arrives as scans, this moves a large category of files from unmatchable to matchable.

The second is reversibility. Files that Hazel has moved can be restored by right clicking them in Finder and choosing Revert, which returns the file to its original location and name and also restores properties such as tags and comments. The documentation adds the obvious caveat: fix the rule afterwards, or the file will be filed the same way again on the next pass.

Smaller additions in version 6 include custom list attributes, which capture lists of items such as tags and let a rule copy them from a parent folder onto a file, handling for locked files, a pause action, and support for macOS 15 Sequoia.

The three places rules stop working

Three behaviours account for most of the reports that Hazel is not doing anything.

Subfolders are ignored by default

Hazel matches items at the top level of a watched folder. A PDF downloaded directly into a subfolder of Downloads will not match a rule that works perfectly for files in Downloads itself. The fix is a separate rule whose only condition is that the item is a folder and whose only action is Run rules on folder contents. It looks like a rule that does nothing, because its effect is to extend every other rule downward.

Sync is not what sync usually means

The Sync action copies items added since the rule last ran. The documentation states the limits directly.

One-way syncing only: Syncing in Hazel is one-way; files changed in the destination folder are not copied back to the monitored folder.

Deletions are not propagated either, because the absence of a file is not something a condition can match. Working around that requires restructuring the rule to watch a subfolder as a whole, which changes the shape of the destination. Anyone expecting the behaviour of a dedicated sync tool will be surprised, and the vendor says as much in the same document.

Nothing runs while Hazel is stopped

Hazel can be stopped from its own menu or the status menu, and while stopped, no rules run and no trash processing happens. Individual rules can be disabled and whole folders can be paused. Each of these is useful during testing and each is easy to leave switched on afterwards. Before investigating anything more complicated, the state of the status menu icon answers the question of whether the engine is even running.

What this tool does not take on

Three jobs sit outside the design, and knowing that in advance prevents a pointless search for the right setting.

Finding files is one. Hazel processes known locations on a schedule of events, so recovering a file whose name and location have both been forgotten is work for search, not for rules.

Deciding the filing scheme is another. Somebody has to determine what folders exist and what belongs in each one, then translate that into conditions. Automation applies a decision, it does not make it.

Handling the unanticipated is the third. A file that matches no rule is left alone, silently. There is no prompt, no queue of unclassified items demanding attention. That silence is correct behaviour for a deterministic engine, and it also means the folder can slowly fill with items that no rule covers while everything appears to be working.

Where the remaining effort goes

After the rules are in place, the work that is left is not the repetitive filing. It is the investigation before a rule exists, and the cleanup when something unexpected arrives. Both involve looking at files, running a command, and checking a result, which means moving between a file browser, a terminal, and whatever is being used to reason about the problem.

That count does not fall as more rules are added. The number of repeated manual operations falls. These are two different measurements, and keeping them separate makes the decision clearer. If most of a day's window switching comes from repeating the same filing steps, a rules engine removes it. If most of it comes from one-off investigation, the number of open windows is the thing to attack, and a single window holding files, terminal, and reasoning targets that directly. For a side by side view of which tool owns which job, the comparison page lays them out.

What to change first

Pick one folder that genuinely collects files and write two rules for it, then check the Rule Status window rather than trusting that it worked. If the rules hold for a week and the remaining friction is investigation rather than repetition, that is a different problem, and Atriens is aimed at it.