DEV Community

Alexsandro Souza
Alexsandro Souza

Posted on • Edited on

Professional macOS Dev Setup 2023

This document describes how I set up my developer environment on a new MacBook.

The steps below were tested on macOS Monterey (12.03), but should work for more recent versions as well.

Contributing: If you find any mistakes in the steps described below, or if any of the commands are outdated, do let me know!

System update

First thing you need to do, on any OS actually, is update the system! For that: Apple Icon > About This Mac then Software Update....

Apple M1 chips

Install the Rosetta2 emulator for the new ARM silicon (M1 chip). Install Rosetta2 using the terminal:

softwareupdate --install-rosetta --agree-to-license
Enter fullscreen mode Exit fullscreen mode

Key Points

  • In general, binaries built just for x86 architecture will automatically be run in x86 mode
  • You can force apps in Rosetta 2 / x86 mode by right-clicking app, click Get Info, check "Open using Rosetta"
  • You can force command-line apps by prefixing with arch -x86_64, for example arch -x86_64 go
  • Running a shell in this mode means you don't have to prefix commands: arch -x86_64 zsh then go or whatever

  • Check which architecture the command support file $(which git)

  • Check which architecture your term is running echo $(arch)

System preferences

If this is a new computer, there are a couple of tweaks I like to make to the System Preferences. Feel free to follow these, or to ignore them, depending on your personal preferences.

In Apple Icon > System Preferences:

  • Trackpad > Tap to click
  • Trackpad > Tracking speed > Fast (all the way to the right)
  • Mouse > Tracking speed > Fast (all the way to the right)
  • Keyboard > Key Repeat > Fast (all the way to the right)
  • Keyboard > Delay Until Repeat > Short (all the way to the right)
  • Dock > Size -> Small; Magnification -> Large

Finder Preferences

  • Preferences -> advanced -> show all filename extensions
  • View -> Show Path bar
  • View -> Show Status bar

Security

I recommend checking that basic security settings are enabled. You will be happy to have done so if ever your Mac is lost or stolen.

In Apple Icon > System Preferences:

  • Users & Groups: If you haven't already set a password for your user during the initial set up, you should do so now
  • Security & Privacy > General: Require password immediately after sleep or screen saver begins (you can keep a grace period of a couple minutes if you prefer, but I like to know that my computer locks as soon as I close it)
  • Security & Privacy > FileVault: Make sure FileVault disk encryption is enabled
  • iCloud: If you haven't already done so during set up, enable Find My Mac

Homebrew

Package managers make it so much easier to install and update applications (for Operating Systems) or libraries (for programming languages). The most popular one for macOS is Homebrew.

Install

An important dependency before Homebrew can work is the Command Line Developer Tools for Xcode. These include compilers that will allow you to build things from source. You can install them directly from the terminal with:

xcode-select --install
Enter fullscreen mode Exit fullscreen mode

Once that is done, we can install Homebrew by copy-pasting the installation command from the Homebrew homepage

x86

This will install the Homebrew under Rosetta. The x86 one under /usr/local

arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
Enter fullscreen mode Exit fullscreen mode

Follow the steps on the screen. You will be prompted for your user password so Homebrew can set up the appropriate permissions.

Once installation is complete, you can run the following command to make sure everything works:

Homebrew installer in native mode

Not under Rosetta. Native one under /opt/homebrew. completely separate from the x86 one under /usr/local

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)
Enter fullscreen mode Exit fullscreen mode

The brew version will be picked depending on what arch you are running the brew command

brew doctor
Enter fullscreen mode Exit fullscreen mode

Usage

To install a package (or Formula in Homebrew vocabulary) simply type:

brew install <formula>
Enter fullscreen mode Exit fullscreen mode

To see if any of your packages need to be updated:

brew outdated
Enter fullscreen mode Exit fullscreen mode

To update a package:

brew upgrade <formula>
Enter fullscreen mode Exit fullscreen mode

Homebrew keeps older versions of packages installed, in case you want to rollback. That rarely is necessary, so you can do some cleanup to get rid of those old versions:

brew cleanup
Enter fullscreen mode Exit fullscreen mode

To see what you have installed (with their version numbers):

brew list --versions
Enter fullscreen mode Exit fullscreen mode

Homebrew Services

A nice extension to Homebrew is Homebrew Services. It will automatically launch things like databases when your computer starts, so you don't have to do it manually every time.

Homebrew Services will automatically install itself the first time you run it, so there is nothing special to do.

After installing a service (for example a database), it should automatically add itself to Homebrew Services. If not, you can add it manually with:

brew services <formula>
Enter fullscreen mode Exit fullscreen mode

Start a service with:

brew services start <formula>
Enter fullscreen mode Exit fullscreen mode

At anytime you can view which services are running with:

brew services list
Enter fullscreen mode Exit fullscreen mode

iTerm2

Since we're going to be spending a lot of time in the command-line, let's install a better terminal than the default one.

brew install --cask iterm2
Enter fullscreen mode Exit fullscreen mode

You can now launch iTerm, through the Launchpad for instance.

Natural text editing

To improve the experience in the terminal enable the Natural text editing option

Preferences -> profiles -> keys -> Key Mappings -> Presents -> Add Natural text editing

More info

Warp Terminal

I started using Warp terminal instead of Iterm2. I think worth check it out.

brew install --cask warp
Enter fullscreen mode Exit fullscreen mode

Install oh-my-zsh

ZSH is already preinstalled in the latest versions of macOS. I also install https://ohmyz.sh/ as it allows for more configuration and is required in some cases.

sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
Enter fullscreen mode Exit fullscreen mode

Install the Oh My Zsh plugins below

brew install zsh-autosuggestions
brew install zsh-syntax-highlighting
Enter fullscreen mode Exit fullscreen mode

To activate the plugins, add the following at the end of your .zshrc:

source /usr/local/share/zsh-autosuggestions/zsh-autosuggestions.zsh
source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
Enter fullscreen mode Exit fullscreen mode

Add the source ~/.bash_profile to .zshrc, this way you will leverage the configuration from that file

Change the ZSH theme. Replace the ZSH_THEME with ZSH_THEME="gnzh".

You will also need to force reload of your .zshrc:

source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

Stats bar

Display macOS system monitor in your menu bar

brew install stats
Enter fullscreen mode Exit fullscreen mode

Create ssh key

Execute the command below to begin the key creation. Press enter all the way to the end

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
Enter fullscreen mode Exit fullscreen mode

Add the new SSH key to the local SSH agent.

ssh-add --apple-use-keychain ~/.ssh/id_rsa
Enter fullscreen mode Exit fullscreen mode

Get the generated public key

cat ~/.ssh/id_rsa.pub
Enter fullscreen mode Exit fullscreen mode

Show all hidden files

Use the command line to show all hidden files as the files you are searching for are going to be hidden by default.

defaults write com.apple.Finder AppleShowAllFiles true
killall Finder
Enter fullscreen mode Exit fullscreen mode

Git

macOS comes with a pre-installed version of Git, but we'll install our own through Homebrew to allow easy upgrades and not interfere with the system version. To do so, simply run:

brew install git
Enter fullscreen mode Exit fullscreen mode

When done, to test that it installed fine you can run:

which git
Enter fullscreen mode Exit fullscreen mode

The output should be /usr/local/bin/git.

Let's set up some basic configuration. Download the .gitconfig file to your home directory:

cd ~
curl -O https://raw.githubusercontent.com/nicolashery/mac-dev-setup/master/.gitconfig
Enter fullscreen mode Exit fullscreen mode

It will add some color to the status, branch, and diff Git commands, as well as a couple aliases. Feel free to take a look at the contents of the file, and add to it to your liking.

Next, we'll define your Git user (should be the same name and email you use for GitHub and Heroku):

git config --global user.name "Your Name Here"
git config --global user.email "your_email@youremail.com"
Enter fullscreen mode Exit fullscreen mode

They will get added to your .gitconfig file.

On a Mac, it is important to remember to add .DS_Store (a hidden macOS system file that's put in folders) to your project .gitignore files. You also set up a global .gitignore file, located for instance in your home directory (but you'll want to make sure any collaborators also do it):

cd ~
curl -O https://raw.githubusercontent.com/nicolashery/mac-dev-setup/master/.gitignore
git config --global core.excludesfile ~/.gitignore
Enter fullscreen mode Exit fullscreen mode

Visual Studio Code

With the terminal, the text editor is a developer's most important tool. Everyone has their preferences, but if you're just getting started and looking for something simple that works, Visual Studio Code is a pretty good option.

Go ahead and download it. Open the .dmg file, drag-and-drop in the Applications folder, you know the drill now. Launch the application.

If you remember only one keyboard shortcut in VS Code, it should be Cmd+Shift+P. This opens the Command Palette, from which you can run pretty much anything.

Let's open the command palette now, and search for Shell Command: Install 'code' command in PATH. Hit enter when it shows up. This will install the command-line tool code to quickly open VS Code from the terminal. When in a projects directory, you'll be able to run:

cd myproject/
code .
Enter fullscreen mode Exit fullscreen mode

Vim

Although VS Code will be our main editor, it is a good idea to learn some very basic usage of Vim. It is a very popular text editor inside the terminal, and is usually pre-installed on any Unix system.

For example, when you run a Git commit, it will open Vim to allow you to type the commit message.

Vim's default settings aren't great, and you could spend a lot of time tweaking your configuration (the .vimrc file). But if you only use Vim occasionally, you'll be happy to know that Tim Pope has put together some sensible defaults to quickly get started.

Using Vim's built-in package support, install these settings by running:

mkdir -p ~/.vim/pack/tpope/start
cd ~/.vim/pack/tpope/start
git clone https://tpope.io/vim/sensible.git
Enter fullscreen mode Exit fullscreen mode

With that, Vim will look a lot better next time you open it!

Python

Before starting the set up, let's look at some issues with M1 architecture.

  • Update the Python pip that comes in the system. You will need it to install some x86 Python dependencies arch -x86_64 /Library/Developer/CommandLineTools/usr/bin/python3 -m pip install --upgrade pip

Troubleshooting

The pip command from pyenv doesn't support the x86 architecture and you might have problems installing some dependencies. Ex. cv2

If you have problems installing dependencies. Use the pip from the system

arch -x86_64 /Library/Developer/CommandLineTools/usr/bin/python3 -m pip install DEP
Enter fullscreen mode Exit fullscreen mode

It is recommended creating a python environment with

/Library/Developer/CommandLineTools/usr/bin/python3 -m venv .venv
arch -x86_64 zsh
source .venv/bin/activate
pip install DEP
Enter fullscreen mode Exit fullscreen mode

IDEA

We need to be able to set the arch -x86_64 when running python scripts from the IDE. In order to do so we need to replace the python bin with this script.

#!/usr/bin/env bash
set -e
arch -x86_64 original_python_bin "$1" "$2" "$3" "$4" "$5" "$6" "$7" "$8" "$9"
Enter fullscreen mode Exit fullscreen mode

Notice that the original python bin was renamed to original_python_bin

Back to the Python instalation

macOS, like Linux, ships with Python already installed. But you don't want to mess with the system Python (some system tools rely on it, etc.), so we'll install our own version using pyenv. This will also allow us to manage multiple versions of Python (ex: 2.7 and 3) should we need to.

Install pyenv via Homebrew by running:

brew install pyenv
Enter fullscreen mode Exit fullscreen mode

When finished, you should see instructions to add something to your profile. Open your .bash_profile in the home directory (you can use code ~/.bash_profile), and add the following line:

if command -v pyenv 1>/dev/null 2>&1; then eval "$(pyenv init -)"; fi
Enter fullscreen mode Exit fullscreen mode

Save the file and reload it with:

source ~/.bash_profile
Enter fullscreen mode Exit fullscreen mode

Before installing a new Python version, the pyenv wiki recommends having a few dependencies available:

brew install openssl readline xz
Enter fullscreen mode Exit fullscreen mode

We can now list all available Python versions by running:

pyenv install --list
Enter fullscreen mode Exit fullscreen mode

Look for the latest 3.x version (or 2.7.x), and install it (replace the .x.x with actual numbers):

pyenv install 3.x.x
Enter fullscreen mode Exit fullscreen mode

List the Python versions you have locally with:

pyenv versions
Enter fullscreen mode Exit fullscreen mode

The star (*) should indicate we are still using the system version, which is the default.

pyenv global 3.x.x
Enter fullscreen mode Exit fullscreen mode

You can switch your current terminal to another Python version with:

pyenv shell 3.x.x
Enter fullscreen mode Exit fullscreen mode

You should now see that version when running:

python --version
Enter fullscreen mode Exit fullscreen mode

In a project directory, you can use:

pyenv local 3.x.x
Enter fullscreen mode Exit fullscreen mode

This will save that project's Python version to a .python-version file. Next time you enter the project's directory from a terminal, pyenv will automatically load that version for you.

For more information, see the pyenv commands documentation.

pip

pip was also installed by pyenv. It is the package manager for Python.

Here are a couple Pip commands to get you started. To install a Python package:

pip install <package>
Enter fullscreen mode Exit fullscreen mode

To upgrade a package:

pip install --upgrade <package>
Enter fullscreen mode Exit fullscreen mode

To see what's installed:

pip freeze
Enter fullscreen mode Exit fullscreen mode

To uninstall a package:

pip uninstall <package>
Enter fullscreen mode Exit fullscreen mode

virtualenv

virtualenv is a tool that creates an isolated Python environment for each of your projects.

For a particular project, instead of installing required packages globally, it is best to install them in an isolated folder, that will be managed by virtualenv. The advantage is that different projects might require different versions of packages, and it would be hard to manage that if you install packages globally.

Instead of installing and using virtualenv directly, we'll use the dedicated pyenv plugin pyenv-virtualenv which will make things a bit easier for us. Install it via Homebrew:

brew install pyenv-virtualenv
Enter fullscreen mode Exit fullscreen mode

After installation, add the following line to your .bash_profile:

if which pyenv-virtualenv-init > /dev/null; then eval "$(pyenv virtualenv-init -)"; fi
Enter fullscreen mode Exit fullscreen mode

And reload it with:

source ~/.bash_profile
Enter fullscreen mode Exit fullscreen mode

Now, let's say you have a project called myproject. You can set up a virtualenv for that project and the Python version it uses (replace 3.x.x with the version you want):

pyenv virtualenv 3.x.x myproject
Enter fullscreen mode Exit fullscreen mode

See the list of virtualenvs you created with:

pyenv virtualenvs
Enter fullscreen mode Exit fullscreen mode

To use your project's virtualenv, you need to activate it first (in every terminal where you are working on your project):

pyenv activate myproject
Enter fullscreen mode Exit fullscreen mode

If you run pyenv virtualenvs again, you should see a star (*) next to the active virtualenv.

Now when you install something:

pip install <package>
Enter fullscreen mode Exit fullscreen mode

It will get installed in that virtualenv's folder, and not conflict with other projects.

You can also set your project's .python-version to point to a virtualenv you created:

pyenv local myproject
Enter fullscreen mode Exit fullscreen mode

Next time you enter that project's directory, pyenv will automatically load the virtualenv for you.

Anaconda and Miniconda

The Anaconda/Miniconda distributions of Python come with many useful tools for scientific computing.

You can install them using pyenv, for example (replace x.x.x with an actual version number):

pyenv install miniconda3-x.x.x
Enter fullscreen mode Exit fullscreen mode

After loading an Anaconda or Miniconda Python distribution into your shell, you can create conda environments (which are similar to virtualenvs):

pyenv shell miniconda3-x.x.x
conda create --name  mycondaproject
conda activate mycondaproject
Enter fullscreen mode Exit fullscreen mode

Install packages, for example the Jupyter Notebook, using:

conda install jupyter
Enter fullscreen mode Exit fullscreen mode

You should now be able to run the notebook:

jupyter notebook
Enter fullscreen mode Exit fullscreen mode

Deactivate the environment, and return to the default Python version with:

conda deactivate
pyenv shell --unset
Enter fullscreen mode Exit fullscreen mode

Known issue: gettext not found by git after installing Anaconda/Miniconda

If you installed an Anaconda/Miniconda distribution, you may start seeing an error message when using certain git commands, similar to this one:

pyenv: gettext.sh: command not found

The `gettext.sh' command exists in these Python versions:
  miniconda3-latest
Enter fullscreen mode Exit fullscreen mode

If that is the case, you can use the following workaround:

brew install gettext
Enter fullscreen mode Exit fullscreen mode

Then add this line to your .bash_profile:

# Workaround for: https://github.com/pyenv/pyenv/issues/688#issuecomment-428675578
export PATH="/usr/local/opt/gettext/bin:$PATH"
Enter fullscreen mode Exit fullscreen mode

pipx

pipx is a tool to help you install and run end-user applications written in Python.

brew install pipx
pipx ensurepath
Enter fullscreen mode Exit fullscreen mode

AWS CLI

Download the pkg installer using the curl command.

curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
Enter fullscreen mode Exit fullscreen mode

Run the standard macOS installer program, specifying the downloaded .pkg file as the source.

sudo installer -pkg ./AWSCLIV2.pkg -target /
Enter fullscreen mode Exit fullscreen mode

If you don't have root permission check here how to install to the current user without sudo

Node.js

The recommended way to install Node.js is to use nvm (Node Version Manager) which allows you to manage multiple versions of Node.js on the same machine.

Install nvm by copy-pasting the install script command into your terminal.

Once that is done, open a new terminal and verify that it was installed correctly by running:

command -v nvm
Enter fullscreen mode Exit fullscreen mode

View the all available stable versions of Node with:

nvm ls-remote --lts
Enter fullscreen mode Exit fullscreen mode

Install the latest stable version with:

nvm install node
Enter fullscreen mode Exit fullscreen mode

It will also set the first version installed as your default version. You can install another specific version, for example Node 10, with:

nvm install 10
Enter fullscreen mode Exit fullscreen mode

And switch between versions by using:

nvm use 10
nvm use default
Enter fullscreen mode Exit fullscreen mode

See which versions you have install with:

nvm ls
Enter fullscreen mode Exit fullscreen mode

Change the default version with:

nvm alias default 10
Enter fullscreen mode Exit fullscreen mode

In a project's directory you can create a .nvmrc file containing the Node.js version the project uses, for example:

echo "10" > .nvmrc
Enter fullscreen mode Exit fullscreen mode

Next time you enter the project's directory from a terminal, you can load the correct version of Node.js by running:

nvm use
Enter fullscreen mode Exit fullscreen mode

npm

Installing Node also installs the npm package manager.

To install a package:

npm install <package> # Install locally
npm install -g <package> # Install globally
Enter fullscreen mode Exit fullscreen mode

To install a package and save it in your project's package.json file:

npm install --save <package>
Enter fullscreen mode Exit fullscreen mode

To see what's installed:

npm list --depth 1 # Local packages
npm list -g --depth 1 # Global packages
Enter fullscreen mode Exit fullscreen mode

To find outdated packages (locally or globally):

npm outdated [-g]
Enter fullscreen mode Exit fullscreen mode

To upgrade all or a particular package:

npm update [<package>]
Enter fullscreen mode Exit fullscreen mode

To uninstall a package:

npm uninstall --save <package>
Enter fullscreen mode Exit fullscreen mode

Yarn

Is a alternative package manage to npm

npm install --global yarn
Enter fullscreen mode Exit fullscreen mode

Java

The recommended way to install Java is to use SDKman (Software development kit Management) which allows you to manage multiple versions of Java on the same machine and

Install

curl -s "https://get.sdkman.io" | bash
Enter fullscreen mode Exit fullscreen mode

Usage

The following command will show you which versions of Java are available to install:

sdk list java
Enter fullscreen mode Exit fullscreen mode

You can find the latest version in that list and install it with (replace .x.x with actual version numbers):

sdk install java 19.x.x
Enter fullscreen mode Exit fullscreen mode

Select the version you want to use

sdk use java 11.x.x
Enter fullscreen mode Exit fullscreen mode

Java version per Project

Want to switch to a specific JDK or SDK every time you visit a project? This can be achieved through an .sdkmanrc file in the base directory of your project. This file can be generated automatically by issuing the following command

sdk env init
Enter fullscreen mode Exit fullscreen mode

To switch to the configuration present in your .sdkmanrc file, simply issue the following command:

sdk env
Enter fullscreen mode Exit fullscreen mode

Managing Java tools

Check all Java softwares available here

Install Maven

sdk install maven
Enter fullscreen mode Exit fullscreen mode

Install VisualVM

sdk install visualvm
Enter fullscreen mode Exit fullscreen mode

Postman

Postman is an API platform for building and using APIs. It is a very useful tool to work with different APIs(REST, Graphql and gRPC)

brew install --cask postman
Enter fullscreen mode Exit fullscreen mode

AltTab

AltTab brings the power of Windows’s “alt-tab” window switcher to macOS.

brew install --cask alt-tab
Enter fullscreen mode Exit fullscreen mode

After installed, use option + tab to navigate through the opened windows

Zoom

Video communication and virtual meeting platform

brew install --cask zoom
Enter fullscreen mode Exit fullscreen mode

Slack

Team communication and collaboration software

brew install --cask slack
Enter fullscreen mode Exit fullscreen mode

Docker

Docker is a set of platform-as-a-service (PaaS) products that use OS-level virtualization to deliver software in packages called containers.

Install

Download the version of docker for osx you want, check here

Create an account here

Then you can download here

Follow all the steps and congrats!You should have downloaded docker

Kubernetes

We will quickly and easily get a Kubernetes cluster up and running by running a kind Kubernetes cluster. Kind is a Kubernetes cluster that leverages Docker to run a cluster.

brew install kind

// Create a new cluster
kind create cluster --name myloca
Enter fullscreen mode Exit fullscreen mode

Deploy a sample workload(Nginx)

kubectl apply -f https://k8s.io/examples/application/deployment.yaml

// See the pods created
kubectl get po
Enter fullscreen mode Exit fullscreen mode

PostgreSQL

PostgreSQL is a popular relational database, and Heroku has first-class support for it.

Install PostgreSQL using Homebrew:

brew install postgresql
Enter fullscreen mode Exit fullscreen mode

It will automatically add itself to Homebrew Services. Start it with:

brew services start postgresql
Enter fullscreen mode Exit fullscreen mode

If you reboot your machine, PostgreSQL will be restarted at login.

GUI

You can interact with your SQL database by running psql in the terminal.

If you prefer a GUI (Graphical User Interface), Postico has a simple free version that let's you explore tables and run SQL queries.

Redis

Redis is a fast, in-memory, key-value store, that uses the disk for persistence. It complements nicely a database such as PostgreSQL. There are a lot of interesting things that you can do with it. For example, it's often used for session management or caching by web apps, but it has many other uses.

To install Redis, use Homebrew:

brew install redis
Enter fullscreen mode Exit fullscreen mode

Start it through Homebrew Services with:

brew services start redis
Enter fullscreen mode Exit fullscreen mode

I'll let you refer to Redis' documentation or other tutorials for more information.

Elasticsearch

Elasticsearch is a distributed search and analytics engine. It uses an HTTP REST API, making it easy to work with from any programming language.

You can use elasticsearch for things such as real-time search results, autocomplete, recommendations, machine learning, and more.

Install

Elasticsearch runs on Java, so make sure you have installed Java already.

Next, install Elasticsearch with:

brew install elasticsearch
Enter fullscreen mode Exit fullscreen mode

Usage

Start the Elasticsearch server with:

brew services start elasticsearch
Enter fullscreen mode Exit fullscreen mode

Test that the server is working correctly by running:

curl -XGET 'http://localhost:9200/'
Enter fullscreen mode Exit fullscreen mode

(You may need to wait a little bit for it to boot up if you just started the service.)

Elasticsearch's documentation is more of a reference. To get started, you can also take a look at Elasticsearch: The Definitive Guide.

GUI

You can interact with the Elasticsearch server using curl, or anything that can send an HTTP request.

However, if you prefer a graphical interface, you can take a look at Dejavu. You can easily install it via the Dejavu Chrome Extension.

Top comments (0)