-
-
Notifications
You must be signed in to change notification settings - Fork 10.7k
docs/Support-Tiers: rewrite for more clarity #21022
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+103
−79
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,134 +1,158 @@ | ||
| --- | ||
| last_review_date: "2025-04-12" | ||
| last_review_date: "2025-11-10" | ||
| --- | ||
|
|
||
| # Support Tiers | ||
|
|
||
| Homebrew has three support tiers. These tiers set expectations for how well Homebrew will run on a given configuration. | ||
| Homebrew defines three support tiers to help users understand how well Homebrew is expected to work on different systems. | ||
|
|
||
| These tiers describe the level of compatibility, automation coverage, and community support that the project actively maintains. They also set expectations for how we handle issues, pull requests, and regressions. | ||
|
|
||
| ## Tier 1 | ||
|
|
||
| A Tier 1 supported configuration is one in which: | ||
| A Tier 1 configuration is considered fully supported. These configurations receive the highest level of CI coverage and are prioritized during issue review and formula development. | ||
|
|
||
| Users can expect: | ||
|
|
||
| - you'll have the best experience using Homebrew | ||
| - we will aim to fix reproducible bugs affecting this configuration | ||
| - we will not output warnings about running on this configuration | ||
| - we have CI coverage for automated testing and building bottles for this configuration | ||
| - your support is best met through Homebrew's issue trackers | ||
| - Homebrew may block merging a PR if it doesn't build properly on this configuration | ||
| - the most reliable experience using Homebrew | ||
| - reproducible bugs to be investigated and, where possible, fixed by Homebrew maintainers | ||
| - no warning output related to system configuration | ||
| - full CI coverage for testing and bottle builds | ||
| - support through Homebrew’s GitHub issue trackers | ||
| - pull requests to be blocked if they fail on Tier 1 systems | ||
|
|
||
| ### macOS | ||
|
|
||
| For Tier 1 support, Homebrew on macOS must be all of: | ||
| To qualify as Tier 1, a macOS configuration must meet all of the following: | ||
|
|
||
| - running on official Apple hardware (e.g. not a "Hackintosh" or VM) | ||
| - running the latest patch release of a macOS version supported by Apple on that hardware | ||
| - running a version of macOS with Homebrew CI coverage (i.e. the latest stable or prerelease version, two preceding versions) | ||
| - installed in the default prefix (i.e. `/opt/homebrew` on Apple Silicon, `/usr/local` on Intel x86_64) | ||
| - running on a supported architecture (i.e. Apple Silicon or Intel x86_64) | ||
| - not building official packages from source | ||
| - installed on your Mac's built-in hard drive (i.e. not external/removable storage) | ||
| - you have `sudo` access on your system | ||
| - the Xcode Command Line Tools are installed and fully up-to-date | ||
| - On official Apple hardware (not a Hackintosh or virtual machine) | ||
| - Running the latest patch release of a macOS version supported by Apple for that hardware and included in Homebrew’s CI coverage (typically the latest stable or prerelease version and the two preceding versions) | ||
| - Installed in the default prefix: | ||
| - `/opt/homebrew` on Apple Silicon | ||
| - `/usr/local` on Intel x86_64 | ||
| - Using a supported architecture (Apple Silicon or Intel x86_64) | ||
| - Not building official packages from source (i.e. using bottles) | ||
| - Installed on the Mac’s internal storage (not external or removable drives) | ||
| - Running with `sudo` access available | ||
| - Xcode Command Line Tools installed and up to date | ||
|
|
||
| ### Linux | ||
|
|
||
| For Tier 1 support, Homebrew on Linux must be all of: | ||
| To qualify as Tier 1, a Linux configuration must meet all of the following: | ||
|
|
||
| - running on Ubuntu or a Homebrew-provided Docker image | ||
| - have a system `glibc` >= 2.35 | ||
| - have a Linux kernel >= 3.2 | ||
| - if running Ubuntu, using an Ubuntu version in "standard support": <https://ubuntu.com/about/release-cycle> | ||
| - installed in the default prefix (i.e. `/home/linuxbrew/.linuxbrew`) | ||
| - running on a supported architecture (i.e. Intel x86_64 or ARM64/AArch64) | ||
| - not building official packages from source | ||
| - you have `sudo` access on your system | ||
| - Running on: | ||
| - Ubuntu within its [standard support window](https://ubuntu.com/about/release-cycle) or | ||
| - a Homebrew-provided Docker image | ||
| - Using a system `glibc` version ≥ 2.35 | ||
| - Using a Linux kernel version ≥ 3.2 | ||
| - Installed in the default prefix: `/home/linuxbrew/.linuxbrew` | ||
| - Using a supported architecture (ARM64/AArch64 or Intel x86_64) | ||
MikeMcQuaid marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Not building official packages from source (i.e. using bottles) | ||
| - Running with `sudo` access available | ||
|
|
||
| ## Tier 2 | ||
|
|
||
| A Tier 2 supported configuration is one in which any of: | ||
| A Tier 2 configuration is not fully supported. These configurations are outside the scope of complete CI coverage and may not consistently function as expected. | ||
|
|
||
| - you get a subpar but potentially still usable experience using Homebrew | ||
| - we review PRs that fix bugs affecting this configuration but will not aim to fix bugs | ||
| - we will output `brew doctor` warnings running on this configuration | ||
| - we have partial CI coverage for testing and building bottles for this configuration so some bottles will not be available | ||
| - we will close issues only affecting this configuration | ||
| - your support is best met through Homebrew's Discussions | ||
| The following conditions typically apply: | ||
|
|
||
| - Homebrew may be usable but with reduced reliability or performance | ||
| - Pull requests that fix issues specific to these configurations may be considered, but maintainers do not commit to resolving related bugs | ||
| - `brew doctor` will output warnings related to configuration | ||
| - CI coverage may be incomplete; bottles may be unavailable or fail to install | ||
| - Issues that only affect these configurations may be closed without investigation | ||
| - Support is generally limited to community responses on Homebrew’s Discussions | ||
|
|
||
| Tier 2 configurations include: | ||
|
|
||
| - macOS prereleases before we state they are Tier 1 (e.g. in March 2025, macOS 16, whatever it ends up being called) | ||
| - Linux versions with a system `glibc` version < 2.35 (but >= 2.13), requiring the Homebrew `glibc` formula to be installed automatically | ||
| - using official packages that need to be built from source due to installing Homebrew outside the default prefix | ||
| (i.e. `/opt/homebrew` on Apple Silicon, `/usr/local` on Apple Intel x86_64, `/home/linuxbrew/.linuxbrew` for Linux) | ||
| - running on a not-yet-supported architecture | ||
| - devices using OpenCore Legacy Patcher with a Westmere or newer Intel CPU | ||
| - macOS prerelease versions before they are promoted to Tier 1 | ||
| - Linux systems with `glibc` versions between 2.13 and 2.34 (Homebrew’s own `glibc` formula will be installed automatically) | ||
| - Homebrew installed outside the default prefix, requiring source builds for official packages (i.e. installing outside `/opt/homebrew`, `/usr/local`, or `/home/linuxbrew/.linuxbrew`) | ||
| - Architectures not yet officially supported by Homebrew | ||
| - Macs using OpenCore Legacy Patcher with a Westmere or newer Intel CPU | ||
|
|
||
| ## Tier 3 | ||
|
|
||
| A Tier 3 supported configuration is one in which: | ||
| A Tier 3 configuration is not supported. These configurations fall far outside Homebrew’s testing infrastructure and may fail to function reliably, even if basic installation is possible. | ||
|
|
||
| - you get a poor but not completely broken experience using Homebrew | ||
| - we strongly recommend migrating to a Tier 1 or 2 configuration or a non-Homebrew tool | ||
| - we will only review PRs with a very high bar: any changes must be proven by the author to fix (not work around) an issue and not come with high maintainability costs (no patches) | ||
| - we will generally not aim to fix bugs ourselves affecting this configuration | ||
| - we may intentionally regress functionality on this configuration if it e.g. improves things for other configuration | ||
| - we will output noisy warnings running on this configuration | ||
| - we are lacking any CI coverage for testing or building bottles for this configuration so few bottles will be available | ||
| - we will close without response issues only affecting this configuration | ||
| - your support is best met through Homebrew's Discussions | ||
| The following conditions typically apply: | ||
|
|
||
| Tier 3 configurations include: | ||
| - Homebrew may work, but with a poor and unstable experience | ||
| - Migration to a Tier 1 or 2 configuration, or to a non-Homebrew tool, is strongly recommended | ||
| - Pull requests must meet a very high bar: they must resolve an issue (not merely work around it) and must not introduce high ongoing maintenance cost (e.g. patches must already be merged upstream) | ||
| - Homebrew maintainers do not commit to fixing bugs affecting these systems | ||
| - Functionality may regress intentionally if it benefits supported configurations | ||
| - Loud configuration warnings will be printed at runtime | ||
| - CI coverage is unavailable; bottles will rarely be built or published | ||
| - Issues affecting only these configurations may be closed without response | ||
| - Support is limited to community replies via Homebrew’s Discussions | ||
|
|
||
| - macOS versions for which we no longer provide CI coverage and Apple no longer provides most security updates for (e.g. as of March 2025, macOS Monterey/12 and older) | ||
| - building official packages from source when binary packages are available | ||
| - installing Homebrew outside the default prefix (i.e. `/opt/homebrew` on Apple Silicon, `/usr/local` on Apple Intel x86_64, `/home/linuxbrew/.linuxbrew` for Linux) | ||
| - installing formulae using `--HEAD` | ||
| - installing deprecated or disabled formulae | ||
| - devices using OpenCore Legacy Patcher with an Intel CPU older than Westmere | ||
| Tier 3 configurations include: | ||
|
|
||
| We build a Portable Ruby for some Tier 3 supported configurations. | ||
| - macOS versions no longer covered by CI and no longer receiving regular Apple security updates | ||
| - Systems that build official packages from source despite available bottles | ||
| - Homebrew installed outside the default prefix (e.g. `/opt/homebrew`, `/usr/local`, or `/home/linuxbrew/.linuxbrew` used on mismatched architectures) | ||
| - Installing formulae using `--HEAD` | ||
| - Installing deprecated or disabled formulae | ||
| - Macs using OpenCore Legacy Patcher with an Intel CPU older than Westmere | ||
|
|
||
MikeMcQuaid marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ## Unsupported | ||
|
|
||
| An unsupported configuration is one in which: | ||
|
|
||
| - Homebrew will refuse to run at all without third-party patching | ||
| - You must migrate to another tool (e.g. Tigerbrew, MacPorts, Linux system package managers etc.) | ||
| - Homebrew will not run without third-party patches or modifications | ||
| - Migration to another tool is required (e.g. Tigerbrew, MacPorts, or a native Linux package manager) | ||
|
|
||
| Unsupported configurations include: | ||
|
|
||
| - FreeBSD | ||
| - Mac OS X 10.6 | ||
| - macOS Mojave 10.14 and earlier | ||
| - Beowulf clusters | ||
| - Nokia 3210s | ||
| - CPUs built inside of Minecraft | ||
| - toasters | ||
| - Toasters | ||
MikeMcQuaid marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Unsupported Software | ||
|
|
||
| All packages installed from third-party taps outside of the Homebrew GitHub organisation are unsupported by default. | ||
| Packages installed from third-party taps outside the Homebrew GitHub organization are unsupported by default. | ||
|
|
||
| We may assist the maintainers/contributors/developers of such packages to fix bugs with the Homebrew formula/cask/tap system, but we are not responsible for resolving issues when using that software. | ||
| While Homebrew may assist third-party maintainers in resolving issues related to the formula, cask, or tap system itself, it does not provide support for the behavior or operation of third-party software. | ||
|
|
||
| Bugs that only manifest when using third-party formulae/casks may be closed. | ||
| Bugs that occur only when using third-party formulae or casks may be closed without investigation. | ||
|
|
||
| ## Future macOS Support | ||
|
|
||
| Apple has announced that macOS Tahoe 26 will be the last version of macOS that runs on Intel x86_64. | ||
| As a result, Homebrew will also drop macOS Intel x86_64 support in a future release. | ||
| Apple has announced that macOS Tahoe 26 will be the final version of macOS to support Intel x86_64 hardware. In alignment with this change, Homebrew plans to remove support for macOS on Intel in a future release after that point. | ||
MikeMcQuaid marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| The following timeline outlines expected Tier classifications based on Apple’s release cycle and Homebrew’s CI coverage. | ||
|
|
||
| - As of November 2025: | ||
|
|
||
| Here's the timescale for planned future Tier support: | ||
| Apple Silicon: | ||
| - Tier 1: macOS Tahoe 26, Sequoia 15, Sonoma 14 | ||
| - Tier 3: macOS Big Sur 11 through Ventura 13 | ||
|
|
||
| - Today (November 2025): | ||
| - Tier 1: macOS Tahoe 26, Sequoia 15, Sonoma 14 on Apple Silicon and Intel x86_64 | ||
| - Tier 3: macOS Catalina 10.15 - Ventura 13 | ||
| Intel x86_64: | ||
| - Tier 1: macOS Tahoe 26, Sequoia 15, Sonoma 14 | ||
| - Tier 3: macOS Catalina 10.15 through Ventura 13 | ||
| - Unsupported: macOS Mojave 10.14 and earlier | ||
| - September (or later) 2026: | ||
| - Tier 1: macOS 27, Tahoe 26, Sequoia 15 on Apple Silicon | ||
| - Tier 3: macOS Big Sur 11 - Sonoma 14 on Apple Silicon, macOS Big Sur 11 - Tahoe 26 on Intel x86_64 | ||
|
|
||
| - Expected in or after September 2026: | ||
|
|
||
| Apple Silicon: | ||
| - Tier 1: macOS 27, Tahoe 26, Sequoia 15 | ||
| - Tier 3: macOS Big Sur 11 through Sonoma 14 | ||
|
|
||
| Intel x86_64: | ||
| - Tier 3: macOS Big Sur 11 through Tahoe 26 | ||
MikeMcQuaid marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Unsupported: macOS Catalina 10.15 and earlier | ||
| - September (or later) 2027: | ||
| - Tier 1: macOS 28, macOS 27, macOS Tahoe 26 on Apple Silicon | ||
| - Tier 3: macOS Monterey 12 - Sequoia 15 on Apple Silicon | ||
| - Unsupported: macOS Big Sur 11 and earlier on Apple Silicon, macOS on Intel x86_64 | ||
|
|
||
| - Expected in or after September 2027: | ||
|
|
||
| Apple Silicon: | ||
| - Tier 1: macOS 28, 27, Tahoe 26 | ||
MikeMcQuaid marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Tier 3: macOS Monterey 12 through Sequoia 15 | ||
| - Unsupported: macOS Big Sur 11 | ||
|
|
||
| Intel x86_64: | ||
| - Unsupported: all macOS versions | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.