The prefix directory is the formula’s install location for versioned binaries and packaged assets, while the etc directory is intended for shared configuration that should persist across upgrades. For applications with user-tuned settings, etc is the better home for mutable files because Homebrew preserves it separately from the formula payload. That distinction is essential for upgrade-safe packaging.
Prefix versus etc: how Homebrew separates payload from configuration
Homebrew’s prefix is the formula installation root, so it contains the versioned files that are replaced when the package is upgraded. The etc directory is separate by design, which lets configuration survive reinstallations and formula changes. That separation matters because it keeps mutable local settings out of the package payload and reduces accidental overwrite during upgrades.
The practical distinction is that prefix should be treated as managed software content, while etc is the home for operator-edited configuration. When a tool expects a single config file, the safe pattern is to store the shipped default in prefix and place the user-maintained version in etc, then have the application read the external file first or merge settings at runtime.
A good mental model is that prefix answers “what Homebrew installed,” while etc answers “what the operator tuned.” If configuration stays in prefix, an upgrade can replace it as part of the formula payload, which creates drift, surprises, and sometimes service outages. If it lives in etc, the file remains outside the normal upgrade path and is easier to reason about across versions.
What changes when configuration moves out of prefix
The main operational benefit is upgrade safety. Files under prefix are tied to a specific formula version and are expected to be disposable from Homebrew’s point of view, so they are a poor place for mutable state. Files under etc are intended to persist, which makes them better for application options, local overrides, and any setting an administrator may need to preserve between package updates.
This separation also supports cleaner troubleshooting. If the application fails after an upgrade, you can more easily distinguish a packaging change in prefix from a local override in etc. That reduces the chance of blaming the wrong layer and helps you confirm whether the issue comes from the formula, the runtime, or the persisted configuration.
- Put vendor-supplied defaults and executable assets in prefix.
- Put user-edited, persistent settings in etc.
- Expect prefix contents to change with upgrades, and etc contents to remain stable unless an operator edits them.
- Check the application’s documented config search path before relocating files, because some tools only read one location by default.
For operators who manage many developer or automation hosts, the distinction becomes more important at scale because it prevents configuration from being silently reset by routine package maintenance. It also makes change control simpler: updates to prefix are package events, while updates to etc are environment-specific configuration events that should be tracked separately.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
CIS Controls v8 and NIST CSF 2.0 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| CIS Controls v8 | CIS 4 — Secure Configuration of Enterprise Assets and Software | Homebrew directory separation is a secure configuration and upgrade-safety issue. |
| Recommendation — Store mutable config outside the package payload and keep defaults version-controlled. | ||
| NIST CSF 2.0 | PR.IP-1 — Configuration Baseline | The prefix and etc split distinguishes packaged baseline files from local configuration. |
| PR.MA-1 — Maintenance and Repair | Upgrades can replace prefix contents, so maintenance must respect preserved local state. | |
| PR.AC-1 — Identity and Access Control | Only authorized operators should modify preserved configuration in etc. | |
| Recommendation — Maintain a baseline for package files and preserve local configuration separately. Protect locally managed settings during software maintenance and upgrades. Restrict write access to persisted configuration files and related directories. | ||
Practitioner Guidance
What to verify: Confirm whether the application actually loads its configuration from etc, or whether you need to add a symlink, environment variable, or explicit path flag. The safe location only helps if the software is pointed at it consistently.
Decision rule: If a file must survive formula upgrades or be edited by an operator, place it in etc. If it is part of the shipped package and should be replaced with each version, keep it in prefix.
Common mistake: Treating prefix as a convenient catch-all for config because it is where the software lives. That approach works until the next upgrade, when the formula may overwrite local edits or leave the app reading stale defaults.
Practitioner takeaway: Use prefix for managed package content and etc for durable, operator-owned configuration, then document the application’s lookup order so upgrades do not change behavior unexpectedly.
Related resources from NHI Mgmt Group
- What is the difference between configuration scoring and exposure indicator scanning in Active Directory?
- What is the difference between direct access and effective access in Active Directory?
- What is the difference between application input validation and identity control?
- What is the difference between application access and agent identity governance?
