This tutorial will walk you through how to successfully install Cocos 2d-x and the systems it relies upon, which include:

  • Visual Studio 2013
  • Java Development Kit (JDK)
  • Python 2.7 (not Python 3)
  • Android SDK
  • Apache ANT
  • Android NDK

That’s a lot of things to keep track of! Let’s walk through the download process.

Step 1: Install Visual Studio 2013

Download link:

Where Should I Install It?

You can choose to install all of the components we’ll talk about wherever you want. Their location doesn’t matter, since we’ll be telling the computer where to find them anyway (their path). I recommend putting them all in a single folder located in your C: directory for easy access.

Step 2: Install the Java Development Kit (JDK)

Download link:

To test your installation, open a Command Prompt (terminal). Type java -version, then hit the Enter key. If the terminal returns a valid version number, you did your installation correctly.

Opening the Command Prompt

To access the Command Prompt, go to your computer’s Start Menu. In the Search Programs and Files box, type cmd. This will open a window like this:


Step 3: Install Cocos 2d-x

Download link:

Step 4: Test Cocos 2d-x Installation

Go into your Cocos 2d-x directory (the location where you installed it). Inside that directory, you should see another directory (folder) called build. Go into it and double-click on cocos2d-win32.vc2012 to open the application.

Once Visual Studio opens, you’ll see a pane on the right side called Solution Explorer. Within that pane should be a file called cpp-tests. Right-click on it and select Set as StartUp Project.

Solution Explorer

Once you do that, click on Local Windows Debugger to compile the test program. This will take awhile.

Local Windows Debugger

Once it completes, it should open a window that looks like this:

CPP Tests

You can close out of the window and Visual Studio now — your installation was successful!

Step 5: Install Python 2.7

Download link:

Make sure when you are installing Python that you select Add python.exe to path. This will tell your computer where to find the location of the Python install without you having to do it manually. Note that adding python’s path is not done by default, so make sure you select that option!

Python 2.7

What About Python 3?

Cocos 2d-x will not work with Python 3 if you have a version of Cocos 2d-x before 3.3. More recent versions of Cocos 2d-x may or may not work with Python 3. To be on the safe side, you should install and use Python 2.7.

If you already have Python 3, go into its directory (usually in C:) and change it’s executable from python to python3. This way, a call to python will default to Python 2.7, but you can still use python 3 if you need to in another program (e.g. the Command Prompt) by calling python3 instead of python.

To test your python installation, open the Command Prompt and type python. If the prompt returns a valid version number, you did the installation correctly.

Step 6: Install Android SDK (Stand-Alone Tools)

Download link:

Why Not Just Install Android Studio?

Although Android Studio comes with SDK tools, they are not separate from the studio, which means non-studio applications cannot access them. Therefore, if you choose to install Android Studio, you will still need to install the Stand-Alone Tools to use with Cocos 2d-x.

Once your installation is complete, it will open the SDK Manager automatically (if you also installed Android Studio, you would have to repeat the following instructions within the studio as well by clicking Configure -> SDK Manager on its welcome screen). Select the extra packages recommended by the Android SDK website (on the page that pops up after you download the tools) and install them. There should be about 17-20 you should install, depending on your needs.

Android SDK Manager

You’ll need to add the location of the SDK tools subfolder to your computer’s Path variable (e.g. ;C:\Program Files (x86)\Android\android-sdk\tools). See the next step for how to add something to the Path variable.

Step 7: Install Apache ANT

Download link:

Now we need to start getting serious about telling the computer where to find all the stuff we’ve been downloading. We do that by creating Environmental Variables and adding the location of our downloads to our system’s Path variable.

Go to the Start Menu on your computer and right-click on Computer -> Properties.


Choose Advanced System Settings

Advanced Systems Settings

Then click Environment Variables.

Environmental Variables

Ignore top window (user variables) and be sure to only work in the bottom window (system variables).

Environmental Variables - Inside

Create a new environmental variable called JAVA_HOME. (You need to tell the computer the location of Java in order to run ANT.) Set its location as the path of all the folders you have to navigate through to get to that program (starting with C: and ending in jre). E.g. C:\Program Files\Java\jdk1.8.0_20\jre

Add both Java’s and ANT’s complete paths to the system’s Path variable. Preface each path by ; to separate it from other paths in the list. Do not include spaces unless they’re in the path name. E.g. ;C:\apache-ant-1.9.4\bin;C:\Program Files\Java\jdk1.8.0_20\jre

To test your ANT installation, open the Command Prompt and type ant -version. If the prompt returns a valid version number, you did the installation correctly.

Step 8: Android NDK

Download link:

Special Case for Cocos 2d-x versions before 3.3

Cocos 2d-x will not work with Android NDK 10+ if you have a version of Cocos 2d-x before 3.3. Instead, you need Android NDK 9. It’s downloaded link is here.

Step 9: Tie It All Together

Now that we’ve downloaded everything, we need to tell the computer where to find it all.

Open the Command Prompt. Navigate into your Cocos 2d-x director using cd. E.g. cd Documents\cocos-2d-x-3.4

Type python (In addition to performing necessary setup operations, this action will set the NDK, SDK, and ANT environmental variables/paths so you don’t have to do it yourself).

When prompted, provide the

  • NDK path (e.g. C:\android-ndk-r10d)
  • SDK path (e.g. C:\Program Files (x86)\Android\android-sdk)
  • ANT root (e.g. C:\apache-ant-1.9.4\bin)

and then hit the Enter key. Be careful not to type Enter before you’ve typed the path or else you’ll skip creating the necessary variable and path location in your computer’s system!

Finally, close and then reopen the Command Prompt to force the systems variables you just added to take effect.