Please note that this guide was last updated on 29th May 2017. I haven’t worked with Cordova since 2018 and so the steps below are likely out of date and may not work. I’m keeping the guide here as a historical reference. If you are interested in providing updated instructions, please reach out to me and I will look to update this post accordingly.
Cordova is a popular framework for building hybrid mobile applications. This post provides a complete guide on how to install it on a Mac running OS X or macOS, so you can deploy a Cordova-based app to your iOS or Android device.
Since Cordova is the technology that underpins other frameworks such as Ionic, this post also acts as an installation guide for these projects.
To follow through this guide you’ll need:
In addition to the above, the following software is recommended (but not essential):
Running Windows? You can still install Cordova and deploy to an Android device, the instructions can be found in this post.
Briefly, these are steps you need to take:
You need an Apple ID to deploy to iOS devices.
Tip: Even if you already have an Apple ID, consider using a separate Apple ID for development purposes. It will help to separate work and personal life.
Xcode is the IDE used on a Mac to create and publish iOS apps. It also comes with a set of command-line tools which are essential for deploying Cordova apps.
The easiest way to download Xcode is through the Mac App Store:
Xcode is a hefty download, weighing in at over 4GB, so you might want to skip to the next section (installing the Android SDK) while it is downloading, and come back here later.
Once Xcode has installed itself, you should open a Terminal window. Type the following:
If the command line tools are already installed, a message will be shown in the terminal:
xcode-select: error: command line tools are already installed. Otherwise, a pop-up window will appear asking if you want to install the command line tools, click
Yes and wait for these to download and install.
Open Xcode. You should see the Welcome to Xcode screen.
In the top menu, press
Xcode -> Preferences.
In the Accounts tab, press
+ -> Add Apple ID.
Sign in with your Apple ID. When complete, your account will appear in the list. You can now close the Preferences pane.
We’re done with iOS for the time being. In the next section, we’ll set up the Android SDK.
The Android SDK is used to build Android apps. There are a few steps involved to get the Android SDK:
We’ll cover these steps now.
.dmgfile has downloaded, open it.
To check that Java was installed correctly, open a terminal window and type
java -version. You should see the Java version printed to the terminal.
toolsfolder from the zip into the new
When you are done, you should have a new folder at
We’ll now use the Command Line tools to install the SDK and other necessary tools.
cd ~/android/tools/bin ./sdkmanager "build-tools;25.0.3" "emulator" "platforms;android-25" "platform-tools" "system-images;android-25;google_apis;x86" --verbose ./avdmanager -v create avd -n x86 -k "system-images;android-25;google_apis;x86" -g "google_apis"
Make sure to accept the license agreement. Once these commands have completed, your
android folder should contain a whole bunch of new directories, including:
build-tools- these are the tools used by Cordova to build your Android app.
emulator- this is the Android emulator that will be used later to preview the app on your Mac.
platforms- this is the Android SDK, separated by platform version. These correspond to the releases of Android: Nougat, Marshmallow, etc. The command above has downloaded the most recent platform version (25).
platform-tools- more tools that are used to administer Android devices on the command line.
system-images- these are images used by the emulator.
Gradle is a tool that is required by the Android SDK to build Android apps. It used to be included with the Android SDK, but now it must be downloaded and configured manually.
binary-onlyversion of the latest release and select it to begin the download.
gradlefolder to the
androidfolder that was created above.
In order to make this dizzying array of tools available to Cordova, and to us when using the terminal, we need to set some environment variables. To do this:
export ANDROID_HOME=$HOME/android export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/gradle/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools/bin
Enterto save the file.
source ~/.bash_profileto setup the environment variables.
Note: If you are using a different shell (such as zsh) you will need to add the environment variables above to the correct shell file. If you don’t know what shell you are using, ignore this (you’ll be using bash).
To test that all of this has worked, try typing the following into the terminal window:
adb version gradle -v
After running each command, you should see the respective tool print its version number. If any of these commands results in a
command not found, the environment has not yet been setup correctly. Please double check that the above steps have been carried out before continuing.
If you have got this far, congratulations! We have now set up the iOS and Android SDKs. The next step is to install the Cordova CLI and create a sample app.
The Cordova CLI requires node.js. If you have already installed node, you can skip to the next section.
If you have already used npm, you might have found that you can’t install packages without prefixing your command with
sudo. To fix this, it’s recommended to follow these instructions.
npm install -g cordova.
When this finished, you should be able to run the command
cordova -v which should print the cordova version to the terminal.
To deploy to the iOS simulator and devices from the terminal, we should also install two more packages:
npm install -g ios-sim ios-deploy
We’ll use these tools later.
We’ll now create a sample app which we can deploy to the simulator and device.
Open a terminal and change to a folder where you are happy for code to live. The commands below will generate a new cordova project in a subdirectory of whichever folder you are currently in.
For example, if you have code living in folders at
/Users/<username>/Code, change to this directory before running the commands below.
Once you are in the correct directory, run the following:
cordova create cordova-hello-world cd cordova-hello-world cordova platform add ios android cordova build
These commands will create a new cordova project, add the iOS and Android platforms, and build the respective files for deployment to iOS and Android.
Before continuing, please ensure that the commands above all worked correctly, with no errors. If there were any errors, you’ll need to go back and check that the iOS and Android SDKs were both installed correctly, and that you’ve set the environment variables correctly.
Note: if you see the following error:
xcode-select: error: tool 'xcodebuild' requires Xcode ... then run the following commands to try again:
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer cordova build
To deploy the app to the iOS simulator, type:
cordova emulate ios
The iOS simulator should automatically launch. When it has finished initialising, the Cordova Hello World app should be displayed:
To deploy the app to the Android emulator, type:
cordova emulate android
The emulator should launch and display the app:
Note: If you see an error in the terminal such as
Failed to sync vcpu reg when the emulator is starting, this means that the emulator cannot start its virtual machine. To solve this problem, make sure you aren’t running any other virtual machines on your Mac. This includes Virtualbox (or Vagrant), VMWare and Docker. Close all of these applications before trying again.
The final step in the process is to deploy the app to your device(s).
Before the app is deployed, the Bundle ID of the app needs to be changed to something unique. A Bundle ID is used to uniquely identify an app. When building for an iOS device, Xcode will verify that the bundle ID has not been used by any other iOS app.
The convention for a Bundle ID is to use a reverse domain identifier, followed by the name of the app. For example, using a domain
tomspencer.dev and an app name of
Hello Cordova, the Bundle ID would be
dev.tomspencer.hellocordova. If you own a domain, you can use the above convention, otherwise use a random string of alphanumeric characters.
Once you have chosen your Bundle ID, update it by editing the file
config.xml in the project root directory. You are looking for the section that reads
widget id="io.cordova.hellocordova" - change
io.cordova.hellocordova to your new Bundle ID.
When you change the Bundle ID, you need to regenerate the platform files. Do this by running the following commands from the project root directory in the terminal:
cordova platform rm ios android cordova platform add ios android
If you have an iPhone or iPad running iOS 10+, you can deploy the app to your device. You’ll need a lightning cable to connect your iOS device to your Mac.
Before starting with this section, ensure that your device is running the latest version of iOS. You can check this by using the Settings app on the device. Choose General -> Software Update to check if there is an update available. If there is, install it before continuing.
The first time you deploy the app, you’ll need to use Xcode. Carry out the following steps:
cordova build ios open platforms/ios/HelloCordova.xcodeproj
Signing for "HelloCordova" requires a development team.
You should now see the text
iPhone Developer next to the Signing Certificate entry.
Note: if you see the following error:
Failed to create provisioning profile. The app ID cannot be registered to your development team. Change your bundle identifier to a unique string to try again. - this means that the Bundle ID that you set at the start of this section was not unique. Close Xcode, set a new Bundle ID and run through this section again.
Now that the app has been provisioned, it can be deployed to your device.
Note: before the app can be deployed, you may need to wait for the iOS device to ‘finish processing symbol files’. This can take a few minutes.
Xcode will now attempt to build and deploy the app to your device, but it will fail. You’ll see a message in Xcode: Verify the Developer App certificate for your account is trusted on your device. Follow the instructions provided by Xcode to complete this task. Once your account is trusted, you won’t need to perform this step again.
Note: the process of trusting your account requires an Internet connection, so make sure your iOS device is online whilst performing the step above.
Now, return to Xcode and press ‘Play’ again. This time, the app should launch on your device.
Now that Xcode and your iOS device are configured, you can deploy the app from the terminal as follows:
cordova run ios
If you have an Android phone or tablet running Android 4.4+, you can deploy the app to your device. You’ll need a USB cable to connect your device to your Mac.
To begin, you need to configure your device to accept deployments from your Mac:
Your device can now accept app deployments from your Mac.
adb devices. You should see your device listed as attached in the terminal.
You can now deploy the app to your device:
cordova run android
After a short while, the app will be deployed and automatically opened on your device.
You’ve now got Cordova installed, configured and running on your Mac, and you are able to deploy apps to the simulators and devices. You’re in good shape!
I’d recommend taking a look at the Ionic Framework, which builds on Cordova by providing a set of platform-specific UI components and additional build tools to help you build an awesome hybrid mobile app.