Practical macOS Setup Guide for Software Engineers
This is my go-to walkthrough guide for setting up a brand new development environment on macOS after getting a new Mac.
One of the first things I do after getting a new Mac is set up my local development environment. This is my go-to guide for setting up a developer environment on macOS.
Install Xcode Command Line Tools
Unless you're developing software for an Apple device, you won't need to install the entire Xcode application (which is very large - multiple gigabytes 😬). Instead, you just need the command line developer tools.
Install Homebrew
Homebrew is a free and open-source package manager for macOS and Linux – "The Missing Package Manager for macOS" according to its creators.
Homebrew is super helpful for developers because it makes installing, updating, and removing developer tools in macOS from the command line effortlessly. It also makes it possible to install regular apps (known as casks) from the command line and manage them alongside your other packages.
I won't go into all of the nuts and bolts of Homebrew in this post for the sake of brevity; however, you can check out the official Homebrew docs for more information.
Once the above command has been executed, you can check that Homebrew has been installed properly by running:
If Homebrew has been installed correctly, this message should appear: Your system is ready to brew.
Analytics
Homebrew will collect anonymous analytics automatically to improve features and create fixes to the project. I personally like to disable these analytics from getting collected. If you'd like to prevent your data from being collected, run the command brew analytics off. For more information about the information that gets collected, visit the homebrew documentation on analytics.
Install iTerm2
Instead of using the built in terminal app that comes with macOS, I like to install and use iTerm2 as a replacement. I've written a Guide to Creating a Beautiful Terminal Configuration for macOS if you'd like some guidance on getting this set up.
Install Visual Studio Code
This isn't a debate about which code editor is the best, so I'm going to use Visual Studio Code as the example (it's my code editor of choice). It's friendly enough for a beginner but it's also powerful for a professional software engineer too. Feel free to use Vim, Emacs, Atom, Sublime Text, or whatever else you want to use that's popular nowadays 🙂
Install and Configure Git
In simple terms, Git is a version control system that is used by developers to track the changes they make to their code. To install git, you can run the following from your terminal:
When installation is done, test that Git has been installed properly by executing the following command:
The output of the above command should display the version of Git that has been installed. You can also run which git which will output the location of git: /opt/homebrew/bin/git
Configure Git
To differentiate between personal and client projects, I like to put repositories in different directories in conjunction with separate git configurations.
To do this, I create two directories nested under a Projects directory:
- Personal - for all of my personal projects
- Clients - for any client projects
I will also create three git configuration files in the respective directories: a personal configuration, a client configuration, and a main configuration at the root of the file system to link them together. Any projects utilizing git living within those directories will inherit the associated configuration file.
Main
Personal
Clients
Verifying the changes
To verify the changes, create a new repository inside a directory that contains one of the configuration files from the above steps. After creating the repository, execute the command git config -l to show the configuration for that repository.
Using Git Credential Manager
Git will occasionally require credentials to authenticate and authorize actions (for example, pulling or pushing code to a repository on GitHub). Installing the git credential manager makes the management of those credentials easy.
(Optional) Install the Github CLI
(Optional) Install Github Desktop for Mac App
Install Node Version Manager
Sometimes you will need to have multiple versions of Node installed on your Mac. Node Version Manager makes it easy to install and switch between different versions of node from the command line.
After installation, you will likely need to add some additional configuration to your ~/.zshrc file:
Install Node Long Time Support version
Now that you have node version manager installed and configured, you'll need to install a version of node. If your project has a specific version of node, you can install that version by running nvm install <version_tag>; otherwise, go ahead and install the long term support version:
Install Rbenv for Ruby Environment Management
Similarly, if you have a Ruby on Rails project or something similar that requires Ruby, you can use Rbenv - a version manager for Ruby. You will need to install rbenv and ruby-build to take advantage of this version manager:
After those packages have been installed, run the command below and follow the instructions:
Install Ruby using Rbenv
To see available ruby versions:
To install a specific ruby version:
Set the ruby version as default:
Verify the installed version by running:
Install Other Apps
There are many other applications that I will install because I find them helpful during development in one form or another. They aren't necessary but I will typically install them because I have found that I use them at one point or another during development.
Docker
Docker is a tool that developers can use to bundle up their applications into self-contained images for easy, consistent deployment. These packages are called containers and they will usually include all the necessary elements to run an application on top of an operating system. You can pick between the formulae only or the cask (which will install the docker desktop application, docker engine, and docker cli).
Formulae only (will install the docker engine only)
Cask (will install the docker desktop app and docker engine)
Beekeeper Studio
Beekeeper Studio is a modern and easy to use SQL client for MySQL, Postgres, SQLite, SQL Server, and more. There's a community edition that is free, but there are also a few paid versions that come with additional features. If you like the product, consider supporting the creator.
Sublime Merge
Sublime Merge is a git client from the creators of Sublime Text. I find this tool particularly helpful when I want to stage specific lines or when performing a complex rebase.
Postman
Postman is an API client that makes it easy to working with and test APIs.
Figma
Figma is a design tool that enables designers to quickly prototype web and mobile application interfaces. I use Figma to design digital products and prototype concepts that I come up with – including my personal website that you're on right now!
Notion
Notion is a collaborative productivity app that I use for note-taking, task management, document creation, and knowledge sharing.
Rectangle
Rectangle is a macOS app that extends window management capabilities. I use it primarily to resize and move windows using keyboard shortcuts.