< _

Setting Up a Mac for Development

Abstract generated cover for Setting Up a Mac for Development.

A good Mac development setup should do two things:

  • make common work easy
  • stay understandable enough to rebuild later It is tempting to install every tool at once, copy a massive dotfiles repo, and spend a full day polishing the terminal. That can be fun, but it is not the first priority. The first priority is getting to a working baseline:
  • package manager
  • terminal
  • Git
  • SSH keys
  • editor
  • language runtimes
  • project folder
  • a repeatable way to document what you installed Once that exists, you can improve the setup over time.

The Mental Model

Treat your Mac like a development environment that you may need to rebuild. That does not mean every detail has to be automated on day one. It does mean you should avoid mystery state. If a tool matters, you should know:

  • how it was installed
  • where its config lives
  • what projects depend on it
  • how to update or remove it This matters when you get a second machine, migrate to a new Mac, or need to debug why a project works in one place but not another.

Install Command Line Tools

Many development tools on macOS depend on Apple's command line tools. Install them with:

xcode-select --install

This gives you basics like Git, compilers, and system headers that other tooling may need. If you are doing iOS or macOS app development, you may also need full Xcode from the App Store. For web and backend work, the command line tools are usually enough to start.

Install Homebrew

Homebrew is the package manager most Mac developers reach for first. It installs command line tools and desktop apps with predictable commands. Examples:

brew install git
brew install ripgrep
brew install fd
brew install jq
brew install node
brew install python

For apps:

brew install --cask visual-studio-code
brew install --cask iterm2

You do not need to install everything immediately. Start with tools you actually use.

Configure Git

Set your Git name and email:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Pick a default editor if needed:

git config --global core.editor "nvim"

Check your config:

git config --global --list

Git is central enough that it is worth setting up carefully.

Create SSH Keys

If you use GitHub over SSH, create a key:

ssh-keygen -t ed25519 -C "[email protected]"

Then add the public key to GitHub. You can print it with:

cat ~/.ssh/id_ed25519.pub

Test the connection:

ssh -T [email protected]

SSH keys are one of the first things to set up on a new machine because they unblock private repositories and normal Git workflows.

Organize Projects

Pick a predictable project directory. For example: ```plain text ~/Projects/ personal-site/ client-work/ experiments/

The exact names do not matter. Consistency matters.
When projects live in random folders, it becomes harder to find them, back them up, or open them from scripts.
I like having one obvious place where code lives.
## Install Language Runtimes
This depends on what you build.
For Python work, you need a clean virtual environment workflow.
For Node and TypeScript work, you need Node, npm, and probably project-local dependencies.
For Go, install Go and let projects use modules.
Examples:
```bash
python3 -m venv .venv
npm install
go version

The important rule is to prefer project-local dependencies when possible. Do not rely on random global packages unless there is a good reason.

Set Up an Editor

Use the editor you can move quickly in. For me, that often means Neovim. For someone else, it may be VS Code or another editor. The editor should support:

  • search
  • language server diagnostics
  • formatting
  • Git awareness
  • project navigation The editor does not need to be perfect on day one. It needs to be reliable enough that you can work.

Common Mistakes

Mistake 1: Installing everything globally

Global packages are convenient until two projects need different versions. Prefer per-project virtual environments and dependency files.

Mistake 2: Not documenting setup steps

If you spend an hour fixing a setup problem, write down what fixed it. Future you will not remember the exact command.

Mistake 3: Copying dotfiles without understanding them

Dotfiles are useful, but they can hide a lot of behavior. Start small. Add configuration as you need it.

Where This Shows Up in Real Projects

A clean Mac setup matters when moving between projects. One project may be Django. Another may be Go. Another may be an Electron app. If the machine has predictable Git, SSH, terminal, editor, and runtime behavior, switching contexts is much easier. It also matters when you clone a project onto another Mac. If your setup is mostly documented and project dependencies are local, the project is easier to run somewhere else.

Key Takeaways

  • Build a working baseline before polishing details.
  • Use Homebrew for common tools.
  • Configure Git and SSH early.
  • Keep project dependencies local when possible.

  • Document setup steps that were not obvious.

    Related Articles

  • My Neovim Setup for Python, Go, and TypeScript

  • Terminal Tools I Actually Use
  • Git Branching Explained: Feature Branch to Master

← Back to Blog Index