Installing Metasploit Framework on OS X El Capitan

This Guide is adapted from Carlos Perez’s Blog ( (which is a must read) with some additions and fixes to make the setup work on OS X El Capitan. This post should help to alleviate some common issues with installing ruby and the Metasploit Framework on OS X. The main issues being that OS X ships with a newer version of Ruby that is not compatible with Metasploit and the version of libiconv installed with OS X causes issues installing the Nokogiri gem.

Xcode and Command Line Development Tools

The first step is to ensure that Software Update has been run and that OS X is updated. Once OS X has been updated, It is time to install Xcode.

Mac App Store – Xcode

Once Xcode has been installed launch Xcode from Applications and agree to the SDK License Agreement.

Install Xcode developer tools  by typing:

xcode-select --install

Click Install in the dialog box that pops up and the package will be installed.


Ensure that the latest versions of the Java 8 JRE and JDK are installed.


Install homebrew by running the following command:

ruby -e "$(curl -fsSL"

Once Homebrew installs, run ‘brew doctor’ to finalize the installation of homebrew.

brew doctor

Once homebrew is installed and set up, the PATH needs to be updated to ensure that all homebrew binaries are executed correctly.

echo PATH=/usr/local/bin:/usr/local/sbin:$PATH >> ~/.bash_profile

Once this is done, load the new $PATH by sourcing it.

source ~/.bash_profile

From here we need to ensure that both versions and dupes are loaded into homebrew (We load in dupes for later, as a dependency for nokogiri is located in here.)

brew tap homebrew/versions
brew tap homebrew/dupes

Homebrew Installs

Before Metasploit can be installed, some more dependencies should be installed via homebrew.


This can be installed either via the dmg from their site, or via homebrew. Homebrew tends to keep their packages updated and it is quite easy to install and manage.

brew install nmap

Install Ruby 2.1.8

Now time for the part the most frequently causes issues. Ruby 2.1.7 is recommended as seen in this file. Since Homebrew doesn’t have 2.1.7 as an option, we’re going to take whatever 2.1.x it can give us. At the time of writing this, the version pulled was 2.1.8 which works perfectly for us.

brew install homebrew/versions/ruby21

Now, the most important part of the ruby installation, Ensuring that the ruby version you are running is in fact 2.1.8.

ruby –v

If the version of ruby is not version 2.1.8, check which ruby binary is being run by default

which ruby

If the binary being run is not the one from the “usr/local/Cellar/ruby21/2.1.8/bin/” directory, then you will need to modify the “~/.bash_profile” file to adjust your path.

nano ~/.bash_profile

Installing and configuring PostgreSQL

Now, time to install the backend database that Metasploit uses.

brew install postgresql --without-ossp-uuid

If the Homebrew install did NOT complete this for you, the next step is to initialize the database for first time usage.

initdb /usr/local/var/postgres

As of 9.3.5_1 it looks like the homebrew installer wraps up by running this command for you.

Ensure that postgreSQL is set to launch on boot by issuing the following:

mkdir -p ~/Library/LaunchAgents
cp /usr/local/Cellar/postgresql/9.4.5_2/homebrew.mxcl.postgresql.plist ~/Library/LaunchAgents/

Start the PostgreSQL service:

launchctl load -w ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

Create a new user msf* and a database msf with the user msf as the owner.

createuser msf -P -h localhost
createdb -O msf msf -h localhost

*Remember this password as it will be used when configuring Metasploit

Configuring VNCViewer

As Metasploit uses vncviewer for its VNC payloads, and OS X comes with a VNC client, we need to create the needed vncviewer file that will call the OS X vnc viewer.

echo '#!/usr/bin/env bash'>> /usr/local/bin/vncviewer
echo open vnc://\$1 >> /usr/local/bin/vncviewer
chmod +x /usr/local/bin/vncviewer

Installing Metasploit Framework

Installing the following gems needed for running the framework:

gem install pg sqlite3 msgpack activerecord redcarpet rspec simplecov yard bundler

Download the framework and prepare the directories:

cd /usr/local/share/
git clone
cd metasploit-framework
for MSF in $(ls msf*); do ln -s /usr/local/share/metasploit-framework/$MSF /usr/local/bin/$MSF;done
sudo chmod go+w /etc/profile
sudo echo export MSF_DATABASE_CONFIG=/usr/local/share/metasploit-framework/config/database.yml >> /etc/profile

Using brew and bundler the properly supported gems need to be installed.

bundle install

NOTE: Bundler $PATH seems to be screwed at the moment. If bundler is not in your $PATH try running it from the installed location:

$ find /usr/local/lib/ruby -type f -name bundle

$ /usr/local/lib/ruby/gems/2.1.0/bin/bundle install

Now that the framework has been installed, and proper bundles installed. The database connection needs to be configured.

Save the following into /usr/local/share/metasploit-framework/config/database.yml replace <password> with the msf user’s password you set earlier.

vi /usr/local/share/metasploit-framework/config/database.yml

  adapter: postgresql
  database: msf
  username: msf
  password: <password>
  port: 5432
  pool: 75
  timeout: 5

Now that this file has been created, source bash_profile to load the variables for the database.

source /etc/profile
source ~/.bash_profile

Now, to start Metasploit Framework as YOUR USER to it initializes the schema for the database for the first time as a NON ROOT user. Run this from within the /usr/local/share/metasploit-framework directory.


Once the console loads, ensure that the database is connected by issuing:

msf> db_status

it should return:

[*] postgresql connected to msf

Install Armitage

Execute the following commands to prepare the environment and download armitage to the correct location:

brew install pidof
curl -# -o /tmp/armitage.tgz
tar -xvzf /tmp/armitage.tgz -C /usr/local/share
bash -c "echo \'/usr/bin/java\' -jar /usr/local/share/armitage/armitage.jar \$\*" > /usr/local/share/armitage/armitage
perl -pi -e 's/armitage.jar/\/usr\/local\/share\/armitage\/armitage.jar/g' /usr/local/share/armitage/teamserver

Lastly, create sym links for Armitage:

ln -s /usr/local/share/armitage/armitage /usr/local/bin/armitage
ln -s /usr/local/armitage/teamserver /usr/local/bin/teamserver

Due to the way variables are handled when using sudo, you will need to give the –E option.

sudo –E armitage
sudo –E msfconsole

Tagged , , , . Bookmark the permalink.

7 Responses to Installing Metasploit Framework on OS X El Capitan

  1. janmaas1975 says:

    bundle install isn’t working for me

    -bash: bundle: command not found

    please help

  2. Antoine says:

    Thank you so much for this perfect tutorial !

  3. buck says:

    error found in bundle install : –>An error occurred while installing pg (0.18.4), and Bundler cannot continue.
    Make sure that `gem install pg -v ‘0.18.4’` succeeds before bundling.

  4. buck says:

    Need some help, Budle install was not successful:
    An error occurred while installing pg (0.18.4), and Bundler cannot continue.
    Make sure that `gem install pg -v ‘0.18.4’` succeeds before bundling.

  5. I had the same issue with the bundle install

    An error occurred while installing pg (0.18.4), and Bundler cannot continue.
    Make sure that `gem install pg -v ‘0.18.4’` succeeds before bundling.

HTML Injection goes here...