1. What is Homebrew?

Homebrew is a package manager for macOS.

Simple meaning:

Homebrew helps you install, update, remove, and manage software from the terminal.

Example:

brew install php
brew install httpd
brew install mysql@8.4
brew install git
brew install wget

Without Homebrew, you may need to manually download installers, configure paths, manage dependencies, and update tools one by one.

With Homebrew, you can do:

brew install php

and Homebrew automatically downloads PHP, installs it, links it, and manages dependencies.

2. What are the use cases of Homebrew?

Homebrew is mainly used for installing developer tools and applications on macOS.

Common use cases

Use Case	Example
Install programming languages	PHP, Python, Node.js, Go, Ruby
Install web servers	Apache/httpd, Nginx
Install databases	MySQL, PostgreSQL, Redis, MongoDB
Install DevOps tools	Docker CLI, Terraform, Ansible, kubectl, Helm
Install command-line tools	wget, curl, tree, jq, htop
Install GUI apps	Chrome, VS Code, Postman, Slack
Manage services	Start/stop MySQL, Apache, Redis
Upgrade tools	Keep packages updated

Example:

brew install terraform
brew install kubectl
brew install helm
brew install ansible

For GUI apps:

brew install --cask google-chrome
brew install --cask visual-studio-code
brew install --cask postman

3. How is Homebrew different from `brew`?

This is very simple:

Term	Meaning
Homebrew	The package manager software/system
brew	The command used to operate Homebrew

Think like this:

Homebrew = application/platform
brew     = command-line tool to use that platform

Example:

brew install php

Here:

brew

is the command.

Homebrew

is the software behind that command.

Same like:

Git     = software
git     = command

Docker  = platform/software
docker  = command

4. What is `/opt/homebrew`?

Your command shows:

pwd
/opt/homebrew

This means Homebrew is installed here:

/opt/homebrew

On Apple Silicon Macs like M1, M2, M3, M4, Homebrew normally installs into:

/opt/homebrew

On older Intel Macs, it usually installs into:

/usr/local

So your Homebrew installation is normal.

5. What are these files and folders?

You ran:

ls

and got:

AGENTS.md
CODEOWNERS
Cellar
LICENSE.txt
bin
etc
manpages
sbin
CHANGELOG.md
CONTRIBUTING.md
Dockerfile
Library
completions
include
opt
share
CLAUDE.md
Caskroom
Frameworks
README.md
docs
lib
package
var

These are Homebrew’s internal folders and files.

Important folders explained

1. `bin`

/opt/homebrew/bin

This contains executable commands.

Example:

/opt/homebrew/bin/brew
/opt/homebrew/bin/php
/opt/homebrew/bin/mysql
/opt/homebrew/bin/httpd

When you run:

php -v

macOS usually finds PHP from:

/opt/homebrew/bin/php

You can check:

which php
which brew
which mysql

2. `Cellar`

/opt/homebrew/Cellar

This is where Homebrew stores actual installed packages.

Example:

/opt/homebrew/Cellar/php
/opt/homebrew/Cellar/httpd
/opt/homebrew/Cellar/mysql@8.4

If you install PHP, the real files are stored inside Cellar.

Example:

ls /opt/homebrew/Cellar/php

You may see a version folder like:

8.4.x

Meaning PHP version 8.4.x is installed there.

3. `opt`

/opt/homebrew/opt

This contains stable shortcut links to installed packages.

Example:

/opt/homebrew/opt/php
/opt/homebrew/opt/httpd
/opt/homebrew/opt/mysql@8.4

This is very useful because package versions change.

For example, real PHP path may be:

/opt/homebrew/Cellar/php/8.4.7

But stable path is:

/opt/homebrew/opt/php

So in Apache config, we prefer:

LoadModule php_module /opt/homebrew/opt/php/lib/httpd/modules/libphp.so

instead of hardcoding a version path.

4. `etc`

/opt/homebrew/etc

This stores configuration files.

For your PHP, Apache, and MySQL setup, this is very important.

Examples:

/opt/homebrew/etc/httpd/httpd.conf
/opt/homebrew/etc/php/8.x/php.ini
/opt/homebrew/etc/my.cnf

Apache config:

/opt/homebrew/etc/httpd/httpd.conf

PHP config:

php --ini

5. `var`

/opt/homebrew/var

This stores variable data like web files, database files, logs, and runtime data.

Important examples:

/opt/homebrew/var/www
/opt/homebrew/var/mysql
/opt/homebrew/var/log

For Apache web root:

/opt/homebrew/var/www

That is why your website files go here:

/opt/homebrew/var/www/index.php

6. `lib`

/opt/homebrew/lib

This contains libraries used by installed software.

Example: PHP, Apache, MySQL, OpenSSL, and other packages may use shared library files from here.

Usually you do not manually edit this folder.

7. `include`

/opt/homebrew/include

This contains header files used when compiling software.

Mostly useful for developers compiling C/C++ libraries.

Normally you do not touch this.

8. `share`

/opt/homebrew/share

This stores shared files like documentation, examples, shell completions, manual pages, and package resources.

Example:

/opt/homebrew/share/doc
/opt/homebrew/share/man

9. `sbin`

/opt/homebrew/sbin

This contains system/admin-level binaries.

Example: some server tools may place commands here.

10. `Caskroom`

/opt/homebrew/Caskroom

This is used by Homebrew Cask.

Homebrew Cask installs GUI applications.

Example:

brew install --cask google-chrome
brew install --cask visual-studio-code

Those cask-related files are managed here.

11. `Library`

/opt/homebrew/Library

This is Homebrew’s own internal code and formula system.

It contains the logic Homebrew uses to install packages.

You should not manually edit this.

12. `Frameworks`

/opt/homebrew/Frameworks

This may contain macOS framework files used by some packages.

Usually you do not touch it.

6. What are files like `README.md`, `LICENSE.txt`, `CHANGELOG.md`?

These are Homebrew project files.

File	Meaning
`README.md`	Basic documentation
`LICENSE.txt`	License information
`CHANGELOG.md`	Changes between Homebrew versions
`CONTRIBUTING.md`	Guide for people contributing to Homebrew
`CODEOWNERS`	Maintainers/owners for parts of the project
`Dockerfile`	Used for Homebrew development/testing
`AGENTS.md` / `CLAUDE.md`	Guidance files for AI/dev agents inside the repo

For normal usage, you do not need to edit these.

7. Most important folders for you

For PHP, Apache, MySQL development, remember only these:

Folder	Purpose
`/opt/homebrew/bin`	Commands like `php`, `mysql`, `brew`
`/opt/homebrew/Cellar`	Actual installed packages
`/opt/homebrew/opt`	Stable shortcut paths
`/opt/homebrew/etc`	Configuration files
`/opt/homebrew/var/www`	Apache web root
`/opt/homebrew/var/mysql`	MySQL data files
`/opt/homebrew/var/log`	Logs

8. Useful commands to understand your Homebrew setup

Check Homebrew location:

brew --prefix

Check where PHP is installed:

brew --prefix php

Check where Apache is installed:

brew --prefix httpd

Check where MySQL is installed:

brew --prefix mysql@8.4

Check installed packages:

brew list

Check installed services:

brew services list

Check PHP command path:

which php

Check Apache command path:

which httpd

Check MySQL command path:

which mysql

Check package info:

brew info php
brew info httpd
brew info mysql@8.4

9. Should you manually change files inside `/opt/homebrew`?

Mostly no.

Do not manually delete or edit these folders:

/opt/homebrew/Cellar
/opt/homebrew/opt
/opt/homebrew/Library
/opt/homebrew/bin
/opt/homebrew/lib

But you may edit config files inside:

/opt/homebrew/etc

Example:

nano /opt/homebrew/etc/httpd/httpd.conf

And you may add website files inside:

/opt/homebrew/var/www

Example:

nano /opt/homebrew/var/www/index.php

10. Simple mental model

Think of Homebrew like this:

/opt/homebrew
│
├── bin       = commands you run
├── Cellar    = actual installed software
├── opt       = stable shortcuts to software
├── etc       = configuration files
├── var       = websites, databases, logs
├── Caskroom  = GUI app management
└── Library   = Homebrew internal system

So when you run:

brew install php

Homebrew puts PHP mainly into:

/opt/homebrew/Cellar/php

Then creates easy command links in:

/opt/homebrew/bin

And stable reference links in:

/opt/homebrew/opt/php

That is the whole magic.

rajeshkumar

Tutorials

MacOS: What is Homebrew and How to work with it?

1. What is Homebrew?

2. What are the use cases of Homebrew?

Common use cases

3. How is Homebrew different from `brew`?

4. What is `/opt/homebrew`?

5. What are these files and folders?

Important folders explained

1. `bin`

2. `Cellar`

3. `opt`

4. `etc`

5. `var`

6. `lib`

7. `include`

8. `share`

9. `sbin`

10. `Caskroom`

11. `Library`

12. `Frameworks`

6. What are files like `README.md`, `LICENSE.txt`, `CHANGELOG.md`?

7. Most important folders for you

8. Useful commands to understand your Homebrew setup

9. Should you manually change files inside `/opt/homebrew`?

10. Simple mental model

1. What is Homebrew?

2. What are the use cases of Homebrew?

Common use cases

3. How is Homebrew different from brew?

4. What is /opt/homebrew?

5. What are these files and folders?

Important folders explained

1. bin

2. Cellar

3. opt

4. etc

5. var

6. lib

7. include

8. share

9. sbin

10. Caskroom

11. Library

12. Frameworks

6. What are files like README.md, LICENSE.txt, CHANGELOG.md?

7. Most important folders for you

8. Useful commands to understand your Homebrew setup

9. Should you manually change files inside /opt/homebrew?

10. Simple mental model

Related Posts

MacOS: Step-by-Step Tutorial: Install PHP, Apache, and MySQL on macOS using Homebrew

3. How is Homebrew different from `brew`?

4. What is `/opt/homebrew`?

1. `bin`

2. `Cellar`

3. `opt`

4. `etc`

5. `var`

6. `lib`

7. `include`

8. `share`

9. `sbin`

10. `Caskroom`

11. `Library`

12. `Frameworks`

6. What are files like `README.md`, `LICENSE.txt`, `CHANGELOG.md`?

9. Should you manually change files inside `/opt/homebrew`?