Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
[GUIDE] Setup macOS for development: terminals, Ruby on Rails, Node JS, react-native, mobile, DB, etc

MOVED!!! Guide moved on Aug 6 2019

moved to:

Recommended setup for bash on macOS (.bashrc, .bash_profile, etc)

Last update: Aug 2019

Assumptions in regard to existing macOS setup

  1. running macOS >= 10.13 (High Sierra or later)
  2. homebrew properly installed (see chapter below about "Correct Homebrew install/setup")
  3. you are using bash as your login, not zsh or anything else

Install bash version >= 5 via homebrew. The macOS default, that comes with macOS, is still bash v3.2 (!crazy, > 10 years old!). It has some limitations and features that don't work.

brew install bash
# version 5.0.7, on Aug 5 2019

Ensure your macOS user is using this new bash version as a login shell:

# edit the /etc/shells and add the newly isntalled bash as a valid shell option

sudo nano /etc/shells

# at the end of the file, add: /usr/local/bin/bash

# and add a new line at the end of the file, then close and save it.

As a result, your file /etc/shells should have this line added to it: /usr/local/bin/bash

Next, open "System Preferences > Users & Groups", then on the bottom-left click to lock to unlock it (enter macos password). Then right-click on your user in the list and "Advanced Options". In the popup window that opens, under "Login shell", click the dropdown and select /usr/local/bin/bash. Press OK, then restart your macbook.

After reboot, your user will be using bash v5 as login shell.

Handle .bash_profile, .bashrc and other dot files

Based on years of experience, trial-and-error, trust me on this one: you only need 2 files that are bash related in your home folder:

  • .bash_profile : this is loaded once, for every login shell (like when you open up a tab in iTerm2)
  • .bashrc : this is run every time for a non-interactive bash shell (like a script)

So, check your home folder, and remove all other bash or profile related files that are not the 2 mentioned above. Here's a list of other possible files you may have, and you should remove, as they may screw up your setup: .profile, .bash_login, .login, .session, .zshrc

Now, let's setup .bash_profile and .bashrc properly:


Should contiain setup that is used for an interactive login shell. So things like:

  • setup for default language, default editor, history control
  • setup for the bash prompt (format, colors, etc)
  • setup bash-completion
  • maybe setup some aliases for daily use (like aliases for git, or other command line repetitive tasks often used)
  • in the end, it should load the .bashrc file as well

Good starting point example file for .bash_profile. You can copy paste this, it should work out of the box. Check the .bashrc example file below too.

# define some alias commands
alias _react_native_cleanall='watchman watch-del-all; rm -rf node_modules && yarn install; rm -fr $TMPDIR/react-*'

# misc settings
export LANG="en_US.UTF-8"
export HISTCONTROL=ignoreboth:erasedups
export EDITOR=mcedit
shopt -s globstar autocd

export ANDROID_HOME=/Developer/android-sdk

# IMPORTANT !!!  --- include .bashrc ---
[[ -s ~/.bashrc ]] && source ~/.bashrc

# bash prompts
export SUDO_PS1="\[\h:\w\] \u\\$ "

# use bash git prompt (
if [ -f "$(brew --prefix)/opt/bash-git-prompt/share/" ]; then
  __GIT_PROMPT_DIR=$(brew --prefix)/opt/bash-git-prompt/share
  source "$(brew --prefix)/opt/bash-git-prompt/share/"

# bash completion
if [ -f $(brew --prefix)/etc/bash_completion ]; then
  . $(brew --prefix)/etc/bash_completion

# iTerm2 integration
test -e "${HOME}/.iterm2_shell_integration.bash" && source "${HOME}/.iterm2_shell_integration.bash"


Should contain setup for PATH, and other environment variables that are used by all scripts (interactive or not). Remember: .bashrc is included/loaded into .bash_profile.

Recommended .bashrc file contents, for a properly setup (includes ruby / rvm, node / nvm, yarn, etc):

# homebrew 
export PATH="$PATH:/usr/local/bin:/usr/local/sbin"

# setup RVM (ruby version manager)
source "$HOME/.rvm/scripts/rvm"
export PATH="$PATH:$HOME/.rvm/bin" # Add RVM to PATH for scripting

# setup NVM (node version manager)
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/" ] && \. "$NVM_DIR/"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

# add yarn installed global packages to path
export PATH="$PATH:`yarn global bin`:$HOME/.yarn/bin"

Maintenance, help, troubleshooting and what to do when things don't work

For reasons unknown and beside the scope of this guide, your setup may be broken (by OS updates, by un-intentional commands you run, by using sudo when you shouldn't, or by other "things"). Anyway, above all, always beware who and what has access to your laptop and can run scripts or apps on it!.

Broken permissions on your own home folder, regain ownership.

If you run sudo on commands that write insode your home folder, you will run into issues, especially when yoou'll want to move to a different laptop (via Migration Assistant).

To fix these:

# find out what is your username

whoami  # write down the result

# example:  jsmith

# take ownership over your home

cd ~  # go into your home

# take ownership on everything under your home folder (! replace `<jsmith>` with your own username !)
sudo chown -R <jsmith> .  # !!! replace `<jsmith>` with your username
# this will ask for root (macos) password, and then... it will take a while, be patient

Broken Homebrew install, folder /usr/local/ permissions

IMO, as you are the only user of your laptop, you should own the homebrew folder(s):

# find out your username

# replace `<jsmith>` with your own username
sudo chown -R <jsmith> /usr/local/*  # pay atention, you are taking ownership inside the folder /usr/local, not the folder itself
# this will ask for root (macos) password, and then... it will take a while, be patient
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment