Xamarin.Android Manual Installation

Installing Xamarin.Android on your Mac

PDF for offline use
Related Articles:
Related Recipes:
Related Links:

Let us know how you feel about this

Translation Quality


last updated: 2017-02

Most of the time, the installation of Xamarin.Android and it’s required components is done through the Universal Installer, however in certain instances these components will need to be installed manually. This article walks through the installation steps and configuration details required to install the Xamarin.Android platform and its prerequisite components on Mac.


To develop Android applications on a Mac, Xamarin Studio and Xamarin.Android are required to be installed. Both Xamarin Studio and Xamarin.Android can be installed through the Unified Installer, which is accessible through the Downloads page. The Unified (or Universal) Installer will install all products required for development on a Mac, including Xamarin.iOS and Xamarin.Mac.

However in some instances, it may not be possible to use the Unified Installer - for example with a network restriction. In this case, it is possible to download each Xamarin product individually by accessing your store account, and manually installing each.

In this guide, we will walk through manually installing the Xamarin.Android platform and its external components. The following steps are required to manually install Xamarin.Android:

  1. Install the Mono SDK (MDK)
  2. Install the Java SDK (JDK)
  3. Install the Android SDK
  4. Install Xamarin Studio and Xamarin.Android
  5. Configure Xamarin.Android


Xamarin.Android works with the following software versions:

  • The latest version of Xamarin Studio
  • OS 10.10.4 Yosemite or later
  • Java JDK 8 (1.8)

The 64-bit version of JDK 8 (1.8) is recommended. This version is the most straightforward choice for the following reasons:

  1. JDK 8 is backwards compatible with all previous Android API levels.

  2. Xamarin Android 7.0 and later requires JDK 8 in order to use Android Nougat (API 24) or later APIs.

  3. The 64-bit JDK 8 supports the new Android designer features. For example, the 64-bit JDK 8 is required if you want to use custom controls in the Android Designer.

If you still need to use legacy JDK 7 (1.7), JDK 8 can be installed alongside JDK 7. If you are using JDK 7, the 32-bit version must be installed. Also, you can continue to use earlier versions of the JDK if you are specifically targeting earlier Android API levels. The following lists the JDK versions that you can use with Xamarin.Android along with the Android levels that each JDK version supports:

One unfortunate complication with JDK 8 is that is not compatible with the version of Proguard that is currently included in the Android SDK. This incompatibility can cause the following error when you attempt to use the Proguard or Multidex features in Xamarin.Android:

Unsupported class version number [52.0]

For more information about this limitation, see 44187. For more information about Xamarin.Android requirements for Mac OS X, see macOS Requirements.

Install the Mono MDK

Sponsored by Xamarin, Mono is an open source implementation of Microsoft's .NET Framework based on the ECMA standards for C# and the Common Language Runtime. Mono can be leveraged by using Xamarin.iOS, or in this case – Xamarin.Android. You can find out more about Mono by visiting the Mono website.

The Mono MDK for Mac can be found in the Download section of the Mono website:

How to download the Mono MDK from the Mono website

The contents of the .pkg file provide both the runtime framework and a complete development kit. Double-Click to open the file and follow the installation dialog to install the Mono Framework on your Mac, as illustrated below:

Run the Mono MDK installer and follow the installation dialog

Installing Java SDK (JDK)

Starting with OS X 10.8, Java is no longer preinstalled and its installation is trigger-based — that is, the first attempt to use anything Java-related kicks off the guided installation process.

To check if you have a Java runtime installed, and it's version, launch Terminal and enter:

java –version

If no JDK has been installed, Terminal will display:

No Java runtime present, requesting install.

The JDK can be downloaded by visiting Oracle’s website and browsing to the section with the heading Java SE Development Kit. Before downloading, you must first Accept License Agreement in the header. Then download the Mac OS X version by clicking the package name jdk-8u121-macosx-x64.dmg (or later), as shown below:

How to download the Java JDK from the Oracle website

When Java is successfully installed the Java Control Panel will be accessible through System Preferences as illustrated in the screenshots below:

After Java is installed the Java Control Panel will be available in System Preferences


Note: If you encounter errors when installing Java on Mac OS X Yosemite (10.10), you will need to install the latest version, found here. This is due to a bug when in the Java Installer when doing an OS version check.

Install the Android SDK and NDK

The Android SDK contains all the tools and frameworks needed for developing an Android application. There are a number of steps needed to install it correctly, which are described below:

  1. Download Android SDK: The SDK can be downloaded from the Android Studio website and will have a file name like tools_r[x].[x].[x]-macosx.zip. It is not necessary to download the entire Android Studio bundle as we only need the SDK. Instead select the Mac zip file under Get just the command line tools as illustrated below:

    How to download the Android SDK from the Android developer website

  2. Extract the Installer: Move the downloaded zip to the ~/Library/Developer/Xamarin/android-sdk-macosx directory and double-click the file to unpack it. This should create a tools subdirectory.

    The ~/Library directory is hidden in Finder by default and you may need to authenticate with a system administrator password in order to successfully move the file. To view the directory, choose Go in the Finder Menu Bar and press the option (Alt) key to unhide the Library option, as illustrated below:

    When holding the Option key, the Go menu in Finder will show the Library option

  3. Download the Android NDK: The Android Native Development kit is used to embed .NET assemblies into native libraries. While the NDK is generally not used for developing an Android application, we do recommend installing it. The NDK can be downloaded from the Android developer website. Once downloaded, move the file to the same directory as the SDK (~/Library/Developer/Xamarin/) and unzip it. This should create a directory named android-ndk, potentially with a version number in the name.

  4. Run the SDK Manager: To run the SDK Manager, use the android script located in the [AndroidSDK_Directory]/tools/ directory. You can run the script in Finder by double-clicking on it, or via terminal using the following command:

    cd ~/Library/Developer/Xamarin/android-sdk-macosx
  5. Install the required SDK Tools and APIs: Once launched, we can use the Android SDK manager to select the relevant components for installation. The latest version of the following components must always be selected:

    • Android SDK Tools
    • Android SDK Platform-tools
    • Android SDK Build-tools

    These selections are illustrated by the screenshot below:

    In the SDK Manager window, select Android SDK tools, platform tools, and build tools

    It is also recommended that you download the Android Support Library and the Android Support Repository under Extras, as shown below:

    In the SDK Manager window, select Android support repository and Android support library

    To start installation, click the Install [x] packages button, accept the Android SDK licenses on the following screen and click Install, as displayed below:

    How to accept the Android SDK licenses in the license agreement window and begin installation

  6. Install more Android Platforms: Deciding which platforms to install is entirely up to you, although it is recommended that at least the most popular platforms in the Android Dashboard are installed. The SDK manager can be accessed at any time through Xamarin Studio to add new or additional API versions. This is achieved by navigating to Tools > Open Android SDK Manager…

    How to open the Android SDK Manager from the Tools menu item in Xamarin Studio

    Installation of the platforms is done in the same way as Step 5. For each selected platform, install at least the ARM EABI System Image and the corresponding Google API image. You should also consider installing the x86 System Image and Google API image.

    You can select additional Android platforms in the SDK manager window

    Note that API Level 11/Android 3.0 is not supported.

Install Xamarin Studio and Xamarin.Android

After all the building blocks have been installed, it’s time for us to install Xamarin Studio. Xamarin Studio requires that the latest Mono runtime and GTK# libraries are available prior to installation, so it must be installed after Mono.

Xamarin Studio is an open-source Integrated Development Environment (IDE) designed for building Mono-based applications.

To download Xamarin Studio, log in to your Xamarin account on the Store page and navigate to the Downloads Page:

How to download Xamarin Studio from the Xamarin account website

This page enables the download of each individual product that make up Xamarin. From here, download the latest version of Xamarin Studio and Xamarin.Android, as shown in the screenshots below:

Click the OS X button under Xamarin Studio to open the dropdown menu and select the latest version

Click the OS X button under Xamarin.Android to open the dropdown menu and select the latest version

Once downloaded, click on the .dmg file to install the product, then drag it into the Applications folder when requested by the installer.

Configure Xamarin.Android

Finally, after we’ve installed the different parts, we can configure them to complete our installation:

  • Configure the SDKs – Once we’ve installed the SDK prerequisites listed above, we need to configure the paths to the corresponding platform installation directories in Xamarin Studio.
  • Configure the Emulator – In order to run and debug our Xamarin.Android applications, we need to use the Android Virtual Device (AVD) Manager to create and configure devices. Instructions for this can be found in the Configuring the Emulator guide.

Configure the SDKs

In the menu bar, navigate to Xamarin Studio > Preferences > Projects, and locate Android under SDK Locations as illustrated in the screenshot below:

In the Xamarin Studio Preferences window, expand the Projects and SDK Locations items in left side menu and select Android

Configure Java SDK

Xamarin Studio will target the default location for the Java SDK. If we had already installed the Java SDK or if it was installed to a different location than the default, we could then configure that installation path by clicking Browse and navigating to the appropriate path.

Configure the Android SDK

In the Android SDK section of the Locations dialog, we can specify the installation path of our Android SDK. Click Browse, then navigate to the Android SDK directory: ~/Library/Developer/Xamarin/android-sdk-macosx


Congratulations! You can now move on to installing Xamarin.Android for Windows, or continue preparing for development and get your device set up for development or configure the Android emulator.

In this article, we examined the components and steps needed to complete the Xamarin.Android installation. We looked at how to install and configure the required runtimes and SDKs, Xamarin Studio, and how to configure Xamarin.Android for development.

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.