Using the Calabash Installer Script

Easily setting up a Calabash Environment on OS X

PDF for offline use
Related Links:

Let us know how you feel about this


last updated: 2016-02

This guide describes how to install and use the Calabash Sandbox on OS X to get started with creating and using Calabash scripts.


The Calabash Sandbox is the best way for a novice to get started with Calabash. This is a Bash script that will establish a pre-configured Ruby environment with everything necessarily to creating and running tests.

The Calabash installer script will setup the Calabash Sandbox with Ruby 2.1.5-p273 (the same version of Ruby that is used in Xamarin Test Cloud) and the current gems for Calabash iOS, Calabash Android, and Xamarin Test Cloud. This will ensure maximum compatibility between a local test environment and the Xamarin Test Cloud environment.

The Calabash Sandbox ignores the default Ruby configuration on a computer and stores its files in the directory $HOME/.calabash/sandbox. The Sandbox shell has its own PATH, GEM_PATH, and GEM_HOME environment variables, which are updated to reference the Sandbox directory. When the Calabash Sandbox exits, these environment variables are restored to their previous values.

The Calabash Installer will not check to see if the Calabash gems which are currently installed are the most current or up to date gems. The guide Determining the Calabash Version describes how to check what versions of the Calabash gems are installed. How to update the gems is described later on in this guide.


The Calabash Installer script is only available for OS X Yosemite and OS X El Capitan.

The use of Ruby environment managers such as rbenv or RVM in the Calabash Sandbox is not supported.


To install the Calabash Sandbox, run the following script in a Terminal session:

curl -sSL | bash

Do not use sudo to install the Calabash Sandbox.

When installation completes, you should see something like the following:

Done! Installed:
calabash-ios:       0.16.4
calabash-android:   0.5.15
xamarin-test-cloud: 1.1.2
Execute 'calabash-sandbox' to get started!

At this point, you can execute calabash-sandbox in a Terminal session to initiate a sandbox environment. To leave the sandbox environment and return the Terminal session to its previous state, type exit.

Installing Gems

Any gems that are installed with the Calabash Sandbox is running will be kept in the Sandbox's GEM_HOME directory, isolated from and not available outside of the Sandbox.

Updating the Calabash Gems

To update the gems, use the update command for the sandbox:

calabash-sandbox update

Restoring the Sandbox

It is possible to reset the Sandbox environment to the original state by running the following commands in the Terminal:

rm -r ${HOME}/.calabash/sandbox
curl -sSL | bash


This section will identify some common problems when using the Calabash Sandbox and how to address them.

I get the error message /usr/local/bin is not writeable

The script attempts to install the sandbox executable to /usr/local/bin so that it can be easily invoked from the command line. However, if you don't have write permissions in that dir, the install script will not be able to move the script there. You can still run it locally by executing:


from the same directory as you ran the install script.

If you'd like to install it globally, either have an administrator move the calabash-sandbox executable to somewhere in your PATH or modify your .bash_profile, .profile, .zsh etc. to find calabash-sandbox in your PATH. It is not recommended to run the install script under sudo.

I installed the Calabash Sandbox using sudo and now can't restart it

You are strongly discouraged from installing the Calabash Sandbox using sudo. If you have problems starting the Calabash Sandbox after installing it with sudo then you should uninstall the Sandbox by executing:

sudo rm -r ${HOME}/.calabash/sandbox

This will uninstall the the Calabash Sandbox. Install it again, without using sudo.


This guide discussed how to install and use the Calabash Sandbox to get started with creating and running Calabash test scripts.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.