diff --git a/README.macOS.bash b/README.macOS.bash
new file mode 100755
index 0000000000000000000000000000000000000000..aa4cb17e8896b00775c224e25a5d2e701f42b580
--- /dev/null
+++ b/README.macOS.bash
@@ -0,0 +1,94 @@
+#!/bin/bash
+
+if hash brew 2>/dev/null; then
+	  echo "Homebrew is already installed!"
+else
+	  echo "Installing Homebrew..."
+	  ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+fi
+
+brew install bash-completion
+brew install cmake # gporca
+brew install ninja # gporca
+brew install libyaml   # enables `--enable-mapreduce`
+brew install libevent # gpfdist
+brew install apr # gpperfmon
+brew install apr-util # gpperfmon
+brew link --force apr
+brew link --force apr-util
+
+
+# Installing Golang
+mkdir -p ~/go/src
+brew install go # Or get the latest from https://golang.org/dl/
+
+# Installing python libraries
+brew install python
+pip install lockfile psi paramiko pysql psutil setuptools
+pip install unittest2 parse pexpect mock pyyaml
+pip install git+https://github.com/behave/behave@v1.2.4
+pip install pylint
+
+#echo -e "127.0.0.1\t$HOSTNAME" | sudo tee -a /etc/hosts
+echo 127.0.0.1$'\t'$HOSTNAME | sudo tee -a /etc/hosts
+
+
+# OS settings
+sudo sysctl -w kern.sysv.shmmax=2147483648
+sudo sysctl -w kern.sysv.shmmin=1
+sudo sysctl -w kern.sysv.shmmni=64
+sudo sysctl -w kern.sysv.shmseg=16
+sudo sysctl -w kern.sysv.shmall=524288
+sudo sysctl -w net.inet.tcp.msl=60
+
+sudo sysctl -w net.local.dgram.recvspace=262144
+sudo sysctl -w net.local.dgram.maxdgram=16384
+sudo sysctl -w kern.maxfiles=131072
+sudo sysctl -w kern.maxfilesperproc=131072
+sudo sysctl -w net.inet.tcp.sendspace=262144
+sudo sysctl -w net.inet.tcp.recvspace=262144
+sudo sysctl -w kern.ipc.maxsockbuf=8388608
+
+sudo tee -a /etc/sysctl.conf << EOF
+kern.sysv.shmmax=2147483648
+kern.sysv.shmmin=1
+kern.sysv.shmmni=64
+kern.sysv.shmseg=16
+kern.sysv.shmall=524288
+net.inet.tcp.msl=60
+
+net.local.dgram.recvspace=262144
+net.local.dgram.maxdgram=16384
+kern.maxfiles=131072
+kern.maxfilesperproc=131072
+net.inet.tcp.sendspace=262144
+net.inet.tcp.recvspace=262144
+kern.ipc.maxsockbuf=8388608
+EOF
+
+# Step: Create GPDB destination directory
+sudo mkdir /usr/local/gpdb
+sudo chown $USER:admin /usr/local/gpdb
+
+# Step: Configure
+cat >> ~/.bashrc << EOF
+ulimit -n 65536 65536  # Increases the number of open files
+export PGHOST="$(hostname)"
+EOF
+
+# Step: GOPATH for Golang
+cat >> ~/.bash_profile << EOF
+export GOPATH=\$HOME/go:\$HOME/workspace/gpdb/gpMgmt/go-utils
+export PATH=\$GOPATH/bin:\$PATH
+EOF
+
+# Step: speed up compile time (optional)
+cat >> ~/.bashrc << EOF
+
+# This assumes that the macOS machine has 8 threads
+export MAKEFLAGS='-j8'
+EOF
+
+# Step: install any optional tools
+brew install gdb
+
diff --git a/README.macOS.md b/README.macOS.md
new file mode 100644
index 0000000000000000000000000000000000000000..4b1dd7f8361e51900bc9048d339ed90b4dc3a8e3
--- /dev/null
+++ b/README.macOS.md
@@ -0,0 +1,73 @@
+# Readme
+
+We've confirmed that these steps work on a brand new installation of macOS Sierra or a 
+brand new installation of macOS Sierra with [Pivotal's workstation-setup](https://github.com/pivotal/workstation-setup)
+
+## Step: install needed dependencies. This will install homebrew if missing
+```
+./README.macOS.bash
+```
+
+## Step: verify that you can ssh to your machine name without a password
+```
+ssh <hostname of your machine>  # e.g., ssh briarwood
+```
+### If the hostname does not resolve, try adding your machine name to /etc/hosts
+```
+echo -e "127.0.0.1\t$HOSTNAME" | sudo tee -a /etc/hosts
+```
+
+### If you see 'ssh: connect to host <> port 22: Connection refused', enable remote login
+System Preferences -> Sharing -> Remote Login
+
+### If you see a password prompt, authorize your SSH key
+```
+mkdir -p ~/.ssh
+ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
+cat ~/.ssh/id_rsa.pub >>  ~/.ssh/authorized_keys
+```
+
+## Step: Allow ssh to use the version of python in path, not the system python
+#
+```
+mkdir -p "$HOME/.ssh"
+cat >> ~/.bash_profile << EOF
+
+# Allow ssh to use the version of python in path, not the system python
+# BEGIN SSH agent
+# from http://stackoverflow.com/questions/18880024/start-ssh-agent-on-login/18915067#18915067
+SSH_ENV="\$HOME/.ssh/environment"
+# Refresh the PATH per new session
+sed -i .bak '/^PATH/d' \${SSH_ENV}
+echo "PATH=\$PATH" >> \${SSH_ENV}
+
+function start_agent {
+    echo "Initialising new SSH agent..."
+    /usr/bin/ssh-agent | sed 's/^echo/#echo/' > "\${SSH_ENV}"
+    echo succeeded
+    chmod 600 "\${SSH_ENV}"
+    source "\${SSH_ENV}" > /dev/null
+    /usr/bin/ssh-add;
+}
+
+# Source SSH settings, if applicable
+
+if [ -f "\${SSH_ENV}" ]; then
+    . "\${SSH_ENV}" > /dev/null
+    ps -ef | grep \${SSH_AGENT_PID} 2>/dev/null | grep ssh-agent$ > /dev/null || {
+        start_agent;
+    }
+else
+    start_agent;
+fi
+
+[ -f ~/.bashrc ] && source ~/.bashrc
+# END SSH agent
+EOF
+
+sudo tee -a /etc/ssh/sshd_config << EOF
+# Allow ssh to use the version of python in path, not the system python
+PermitUserEnvironment yes
+EOF
+
+```
\ No newline at end of file
diff --git a/README.md b/README.md
index 97bb36b14ca7677ac9acea0d18442a1327008d60..7a3b876923536a9ad4ca5d773890c8187eacc125 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,8 @@ to the segments, and collects the results.
 
 ## Building Greenplum Database with GPORCA
 
+For macOS X developers, follow [these steps](README.macOS.md) for getting your system ready for GPDB 
+
 Currently GPDB assumes ORCA libraries and headers are available in the targeted
 system and tries to build with ORCA by default.  For your convenience, here are
 the steps of how to build the optimizer. For the most up-to-date way of