IDEALIT Passport
Menu

Passport search

Find a mission or fix

Type at least two characters.

    Browse help by symptomBrowse all references
    How to start
    Curriculum previewThis is not your assigned passport. No identity, answers, or completion progress are stored here.How to start your passport
    Handbook / reference

    reference

    Homebrew On macOS (Optional)

    Goal: install command-line tools on a personal Mac when a project requires them.

    View exact sourceReturn to my dashboard

    Goal: install command-line tools on a personal Mac when a project requires them.

    Prerequisites: a personal/assigned Mac where you may install software. Do not install Homebrew on Euler, Blade, or a managed lab machine without owner approval.

    Execution context: macOS laptop - zsh.

    Homebrew is optional. Miniforge's maintainers do not recommend installing Miniforge through Homebrew; use the official Miniforge installer in the Python guide.

    Inspect The Machine#

    uname -s
uname -m
echo "$SHELL"
command -v brew || true

    Expected result: Darwin, the CPU architecture, and normally /bin/zsh. If brew already exists, verify it instead of reinstalling.

    Install From The Official Source#

    Review the current command at https://brew.sh/. As of the verification date, the official installer is:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    Read the script source/URL and prompts before approving. At completion, run the exact Next steps printed by the installer to add Homebrew to the current shell; those commands depend on architecture and install location.

    Close Terminal, open a new one, then verify:

    brew --version
brew doctor

    Install Only Required Tools#

    Search and inspect before installation:

    brew search <tool>
brew info <tool>

    This is a template: replace <tool> with the project-required package name before running it.

    Then install the project-required package:

    brew install <tool>

    Do not install a broad package list from an AI agent without checking why each tool is needed.

    Common Failures And Safe Recovery#

    • brew not found after install: run the exact shell-environment command printed by the installer, then open a new terminal.
    • Permission error: do not use random recursive sudo chown commands. Read the diagnostic and consult the official Homebrew troubleshooting guidance.
    • Project breaks after broad upgrade: restore from the project's declared environment/tool versions; do not make unrequested global upgrades during onboarding.

    Verification#

    • brew --version works in a new terminal.
    • brew doctor output has been read; not every warning requires immediate modification.
    • Only project-required tools were installed.

    Ask For Help When#

    The Mac is centrally managed, installer ownership paths are unexpected, or the suggested fix changes permissions outside the Homebrew prefix.

    Verified: 2026-08-04. Review by: 2027-02-04. Owner: lab software maintainer.