Get started

Here's how to get started with ArcGIS Runtime API for Qt:

  1. Review system requirements
  2. Install and set up
  3. Get an API key (to access services)
  4. Complete the Display a map tutorial

1. System requirements

Ensure your development environment meets the system requirements.

For an overview of this release, including enhancements, deprecations, and known issues, see the release notes.

2. Install and set up

ArcGIS Runtime SDK for Qt has APIs for developing desktop apps for Windows, Linux, and macOS, and mobile apps for iOS and Android. You can install the API on Windows, macOS, or Linux.

You will install the following components on your Windows development machine:

  • Microsoft Visual Studio C++ compiler
  • A Qt Framework for Windows: this framework is available from The Qt Company for developing cross-platform apps. This is not an Esri product.
  • A Qt Framework for Android: (for Android developers) this framework is available from The Qt Company for developing Android apps. This is not an Esri product.
  • Qt Creator: the IDE for Qt app development available from The Qt Company automatically included when you download Qt Framework for Windows. This is not an Esri product.
  • ArcGIS Runtime API for Qt for Windows

Install Visual Studio

The Microsoft Visual Studio compiler is used to build apps with ArcGIS Runtime API for Qt. It is recommended that you uninstall previous versions of Visual Studio and any previous Visual Studio redistributables before installing Visual Studio, or conflicts can occur during installation. Be sure to install the C++ compiler. One way to do this is to select the Visual Studio installation option to use the C++ programming language as your default development environment.

Download the Qt Framework for Windows and Qt Creator

To build an app using the ArcGIS Runtime SDK for Qt, you need the Qt Framework designed to work with your compiler. You can install Qt Frameworks for multiple target platforms on your development machine, side-by-side.

  1. Click Get Qt to download and install the appropriate Qt Framework for Windows. This download includes Qt Creator.
  2. Open SSL support is required. Open SSL allows access to secure services that require user credentials. It is not delivered with the Qt Framework. For more information, see the Qt documentation about adding SSL support to your Qt app.
  3. Install a debugger. See the Qt documentation for Setting Up Debugger.

Install prerequisites for Android app development

Install the prerequisite software for Android app development, including the Java SE Development Kit, Android SDK Tools, Android Platform Tools, the Android NDK, and a USB driver to communicate with a mobile device. See Qt for Android for more information on developing for Android with Qt. Also, be sure to install software versions that conform to the system requirements.

  1. Browse to Getting Started with Qt for Android. Follow the instructions to download and install the prerequisite software. It is suggested that you create a new staging folder to store the prerequisite software, such as C:\Android. This folder is referred to in the download and install instructions as a <staging folder>.
  2. Access the settings for Environment variables on your development machine. You can find this in the Control Panel > Advanced System Settings. If the following system environment variables were not previously established, define them as follows:
    1. Create a system environment variable called JAVA_HOME, and set its location to the Java\JDK folder, for example C:\Program Files\Java\jdk<version>.
    2. Create a system environment variable called ANDROID_NDK_ROOT, and put it in your NDK folder <staging folder>\android-ndk-<version>.
  3. Click Get Qt to locate and download the Qt Framework for Android (on Windows).
  4. Run the Qt for Android installer, accepting all installer defaults.
  5. Set up your environment to use OpenSSL. For more information, see the OpenSSL section in the system requirements topic.
  6. In Qt Creator, click Tools > Options > Devices > Android and fill in the paths. Paths should be similar to the following:
    • JDK Location: C:\Program Files\Java\jdk<version>
    • Android SDK Location: <staging folder>\adt-bundle-windows-<platform>-<date>\sdk
    • Android NDK Location: <staging folder>\android-ndk-<version>

Tell Qt Creator where to find your Qt Framework(s)

It is typical to use one Qt Creator IDE with multiple Qt Frameworks, such as one Framework for desktop development and another to build and deploy to a mobile device. Qt Creator needs to know where to find the Qt Frameworks you want to use. By default, it looks for Qt Frameworks on your development machine, but might not detect all the Qt Frameworks you want to use if you have multiple Qt Frameworks on your development machine or if you later install another Qt Framework.

Follow these steps to tell Qt Creator about additional Qt Frameworks:

  1. Click Tools > Options > Build & Run > Qt Versions, and then click Add.
  2. Browse to the qmake.exe file in the installation folder.
  3. Provide a suitable name for this Qt Framework.
  4. Click Apply.

After completing these steps, the Qt Framework you specified will be shown under the heading Manual. You can now use this Qt Framework to configure kits and projects.

Install ArcGIS Runtime SDK for Qt

  1. Make sure you have read/write access to your desired download and extraction location and that your account has administrative privileges, as installing ArcGIS Runtime SDK for Qt on Windows requires administrative privileges.
  2. Go to your dashboard and select the downloads tab, and then select ArcGIS Runtime SDK for Qt.
    • You must log in with your ArcGIS Developer account to access your dashboard and downloads. If you do not have one, sign up now, it's free.
    • Select the Windows download for the most recent version of ArcGIS Runtime SDK for Qt. Note that you can download older versions as well as other development platforms.
  3. Run the extraction wizard, which asks you to choose an extraction location.
  4. Run setup.exe from your chosen extraction location.
  5. After the setup program finishes, the post-installer starts. This integrates ArcGIS Runtime SDK for Qt with your installation of the Qt Framework and Qt Creator. Choose the Qt components you want to configure, selecting only those components that are installed on your development machine. For each component you choose, you must provide the path to that component. Please note that the post-installer needs read / write access to the User Profile's AppData folder.
    • For Qt Creator, use the path to the Qt Creator app.
    • For Qt Frameworks, use the path to qmake.exe in the Framework's install location.

Configure Qt Creator kits

In Qt Creator, a kit defines how to build an app for a target device. Set up a kit for each target device to which you will deploy your app so that you can develop and test for that device. Each kit must include references to the compiler, the Qt Framework, and the debugger. At minimum, you should set up a desktop kit.

  1. Run Qt Creator.
  2. Click Tools > Options > Build & Run > Kits.
  3. Examine the existing kits. If no existing kit has the settings you want, click Add to create a new kit.
  4. Give the kit an appropriate name.
  5. Set the Device type to to match your target device, such as Desktop.
  6. Choose the appropriate compiler to match the target device.
  7. Choose the Qt Version.
  8. Click OK or Apply to finish creating the kit.

Repeat these steps to add an Android kit if you installed the Qt Framework for Android.

Configure a Qt Creator project

  1. Create a project in Qt Creator for your ArcGIS Runtime API for Qt app. You can use a provided project template to create a new project.
  2. Complete the Display a map tutorial to verify your development environment is properly configured.
  3. When you open a Qt Creator project file for the first time, Qt Creator prompts you to configure the project, which requires choosing the kits to use with the project. Choose the kit(s) you created in the previous step, and then click Configure Project.

You can now build your project in Qt Creator on Windows.

You will install the following components on your macOS development machine:

  • Apple Xcode
  • The Qt Framework for macOS: this framework is available from The Qt Company for developing cross-platform applications. This is not an Esri product.
  • The Qt Framework for iOS: (for iOS developers) this framework is available from The Qt Company for developing iOS applications. This is not an Esri product.
  • The Qt Framework for Android: (for Android developers) this framework is available from The Qt Company for developing Android applications. This is not an Esri product.
  • Qt Creator: the IDE for Qt application development available from The Qt Company bundled with Qt Framework for macOS. This is not an Esri product.
  • ArcGIS Runtime SDK for Qt for macOS

Install Xcode

Install Xcode and the Xcode command line tools from the App Store or Apple's developer web site. An Apple developer account is required to log in. Follow the documentation at Apple's accounts web site.

Download the Qt Framework for macOS and Qt Creator

To build an application using ArcGIS Runtime API for Qt, you need the Qt Framework designed to work with your compiler. You can install Qt Frameworks for multiple target platforms on your development machine, side-by-side.

Download and install the Qt Framework for macOS from The Qt Company. Make sure that you also install Qt Creator along with the Qt Framework.

Install prerequisites for iOS development

If you plan to develop applications for the iOS platform, you must install Xcode for iOS. See Qt for iOS for more information on Qt for iOS.

  1. Start Xcode.
  2. Click Xcode > Preferences.
  3. On the Downloads tab, click Component, and download the iOS simulator.
  4. Configure your Xcode for Distribution by following the documentation at Apple's web site.
  5. Download and install the Qt Framework for iOS (on Mac) from The Qt Company.

Install prerequisites for Android development

Install the prerequisite software for Android app development, including the Java SE Development Kit, Android SDK Tools, Android Platform Tools, and the Android NDK. See Qt for Android for more details on developing for Android with Qt. Be sure to install software versions that conform to the system requirements.

  1. Browse to Getting Started with Qt for Android. Follow the instructions there to download and install the prerequisite software. It is suggested that you create a new staging folder to store all the prerequisite software, such as ~/Android. This folder is referred to in the download and install instructions as a <staging folder>.
  2. Download the Qt Framework for Android (on Mac) from The Qt Company.
  3. Run the Qt Framework for Android installer, accepting all installer defaults.
  4. Set up your environment to use OpenSSL. For more information, see the OpenSSL section of the system requirements.
  5. In Qt Creator, click Qt Creator > Preferences > Devices > Android, and fill in the paths. Paths should be similar to the following:
    • JDK Location: <staging folder>/CurrentJDK/Home
    • Android SDK Location: <staging folder>/adt-bundle-mac-x86_64-<date>/sdk
    • Android NDK Location: <staging folder>/android-ndk-<version>

Tell Qt Creator where to find the Qt Framework

It is typical to use one Qt Creator IDE with multiple Qt Frameworks, such as one Framework for desktop development and another to build and deploy to a mobile device. Qt Creator needs to know where to find the Qt Frameworks you want to use. By default, it looks for Qt Frameworks on your development machine, but might not detect all the Qt Frameworks you want to use if you have multiple Qt Frameworks on your development machine or if you later install another Qt Framework.

Follow these steps to tell Qt Creator about additional Qt Frameworks:

  1. Start Qt Creator.
  2. Click Qt Creator > Preferences > Build & Run > Qt Versions, and then click Add.
  3. Browse to the qmake file in the installation location.
  4. Provide a suitable name for this Qt Framework.
  5. Click Apply.

After completing these steps, the Qt Framework you specified will be shown under the heading Manual. You can now use this Qt Framework to configure kits and projects.

Repeat these steps for any Qt Frameworks for Android and iOS you previously installed.

Install ArcGIS Runtime SDK for Qt

  1. Make sure you have read/write access to your desired download and extraction location.
  2. Go to your dashboard and select the downloads tab, and then select ArcGIS Runtime SDK for Qt.
    • You must log in with your ArcGIS Developer account to access your dashboard and downloads. If you do not have one, sign up now, it's free.
    • Select the macOS download for the most recent version of ArcGIS Runtime SDK for Qt. Note that you can download older versions as well as other development platforms.
  3. Run the installer app.
  4. After the installer app finishes, the post-installer starts. This integrates ArcGIS Runtime API for Qt with your installation of the Qt Framework and Qt Creator. Choose the Qt components you want to configure. Choose only components that are installed on your development machine. For each component you choose, you must provide a path to the component. Note that the post-installer needs read/write access to ~/.config.
    • For Qt Creator, use the path to the Qt Creator app.
    • For Qt Frameworks, use the path to the qmake executable in the Framework's install location.

Configure Qt Creator kits

In Qt Creator, a kit defines how to build an app for a target device. Set up a kit for each target device on which you will deploy your app to so that you can develop and test for that device. A kit includes references to the compiler, the Qt Framework, and the debugger. At minimum, you should set up a desktop kit.

  1. Run Qt Creator.
  2. Click Qt Creator > Preferences > Build & Run > Kits.
  3. Examine the existing kits. If no existing kit has the settings you want, click Add to create a new kit.
  4. Give the kit an appropriate name.
  5. Set Device type to to match your target device, such as Desktop.
  6. Choose the Qt Version.
  7. Click OK or Apply to finish creating the kit.

Repeat these steps to add an iOS or Android kit if you installed those Qt Frameworks.

Configure a Qt Creator project

  1. Create a project in Qt Creator for your ArcGIS Runtime API for Qt app. You can use a provided project template to create a new project.
  2. Complete the Display a map tutorial to verify that your development environment is properly configured.
  3. When you open a Qt Creator project file for the first time, Qt Creator prompts you to configure the project, which requires choosing the kits to use with the project. Choose the kit(s) you created in the previous step, and then click Configure Project.

You can now build your project in Qt Creator on macOS.

You will install the following components on your Linux development machine:

  • The Qt Framework for Linux: this framework is available from The Qt Company for developing cross-platform applications. This is not an Esri product.
  • The Qt Framework for Android: (for Android developers) this framework is available from The Qt Company for developing Android applications. This is not an Esri product.
  • Qt Creator: the IDE for Qt application development available from The Qt Company bundled with The Qt Framework for Linux. This is not an Esri product.
  • ArcGIS Runtime SDK for Qt for Linux

Download the Qt Framework for Linux and Qt Creator

To build an application using the ArcGIS Runtime SDK for Qt, you will need the Qt Framework designed to work with your compiler. You can install Qt Frameworks for multiple target platforms on your development machine, side-by-side.

  • Download and install the appropriate Qt Framework for Linux from The Qt Company. Make sure that you also install Qt Creator along with the Qt Framework.
  • Open SSL support is required. Open SSL allows access to secure services that need user credentials. It is not delivered with the Qt Framework. For more information, see the Qt documentation about adding SSL support to your Qt application.

Install prerequisites for Android development

Install the prerequisite software for Android app development, including the Java SE Development Kit, Android SDK Tools, Android Platform Tools, and the Android NDK. See Qt for Android for details about developing for Android with Qt. Be sure to install software versions that conform to the system requirements.

  1. Browse to Getting Started with Qt for Android. Follow the instructions there to download and install the prerequisite software. It is suggested that you create a new staging folder to store all the prerequisite software, such as ~/Android. This folder is referred to in the download and install instructions as a <staging folder>.
  2. Download the Qt Framework for Android (on Linux) from The Qt Company.
  3. Run the Qt Framework for Android installer, accepting all the installer defaults.
  4. Set up your environment to use OpenSSL. For more information, see the OpenSSL section of the system requirements topic.
  5. In Qt Creator, click Tools > Options > Devices > Android, and fill in the paths. Paths should be similar to the following:
    • JDK Location: <staging folder>/jdkl.<version>
    • Android SDK Location: <staging folder>/android-sdk-linux
    • Android NDK Location: <staging folder>/android-ndk-<version>

Tell Qt Creator where to find the Qt Framework

It is typical to use one Qt Creator IDE with multiple Qt Frameworks, such as one framework for desktop development and another to build and deploy to a mobile device. Qt Creator needs to know where to find the Qt Frameworks you want to use. By default, it looks for Qt Frameworks on your development machine but might not detect all the Qt Frameworks you want to use if you have multiple Qt Frameworks on your development machine or if you later install another Qt Framework.

Follow these steps to tell Qt Creator about additional Qt Frameworks:

  1. Start Qt Creator.
  2. Click Tools > Options > Build & Run > Qt Versions, and then click Add.
  3. Browse to the qmake file in the installation location.
  4. Provide a suitable name for this Qt Framework.
  5. Click Apply.

After completing these steps, the Qt Framework you specified will be shown under the heading Manual. You can now use this Qt Framework to configure kits and projects.

Repeat these steps for any Qt Frameworks for Android you previously installed.

Install ArcGIS Runtime API for Qt

  1. Make sure you have read-write-execute access to your desired ArcGIS installation location.
  2. Go to your dashboard and click the downloads tab, and then click ArcGIS Runtime SDK for Qt.
    • You must log in with your ArcGIS Developer account to access your dashboard and downloads. If you do not have one, sign up now, it's free.
    • Select the Linux download for the most recent version of ArcGIS Runtime SDK for Qt. Note that you can download older versions as well as other development platforms.
  3. Save the file to an installation location large enough to hold the extracted content from the gzip and tar files.
  4. Unzip the ArcGIS Runtime gzip file to get the tar file. At the prompt, type % gunzip .tar.gz.
  5. Extract the product tar file to create the installation directory: % tar xvf .tar.
  6. Run the script ./Setup from the installation location.

    Do not double-click on the file in the file browser and select Run in Terminal, or the post-installer will start and then exit as soon as the terminal window closes.

  7. After the setup program finishes, the post-installer starts. The post-installer integrates the ArcGIS Runtime SDK for Qt with your installation of the Qt Framework and Qt Creator. Choose the Qt components to configure. Choose only those components that are installed on your computer. For each component you choose, provide a path to the component. Please note that the post-installer needs read / write access to ~/.config.
    • For Qt Creator, use the path to the Qt Creator app.
    • For Qt Framework installations, use the path to the qmake executable in the Qt Framework's install location.
  8. Add the path to the ArcGIS Runtime for Qt library files to the environment variable LD_LIBRARY_PATH. The path is <install location>/arcgis/runtime_sdk/<sdk version>/sdk/linux/<platform>/lib. You can do this in your Qt Creator project settings, or by setting the LD_LIBRARY_PATH environment variable before starting Qt Creator.

Configure Qt Creator kits

In Qt Creator, a kit defines how to build an app for a target device. Set up a kit for each target device on which you will deploy your app to so that you can develop and test for that device. A kit includes references to the compiler, the Qt Framework, and the debugger. At minimum, you should set up a desktop kit.

  1. Run Qt Creator.
  2. Click Tools > Options > Build & Run > Kits.
  3. Examine the existing kits. If no existing kit has the settings you want, click Add to create a new kit.
  4. Give the kit an appropriate name.
  5. Set the Device type to to match your target device, such as Desktop.
  6. Choose the appropriate compiler for your development platform.
  7. Choose the appropriate debugger. If there is no appropriate debugger, you will need to install one. Refer to your operating system documentation.
  8. Choose the Qt Version.
  9. Click OK or Apply to finish creating the kit.

Repeat these steps to add an Android kit if you installed the Qt Framework for Android.

Configure a Qt Creator project

  1. Create a project in Qt Creator for your ArcGIS Runtime API for Qt app. You can use a provided project template to create a new project.
  2. Complete the Display a map tutorial to verify that your development environment is properly configured.
  3. When you open a Qt Creator project file for the first time, Qt Creator prompts you to configure the project. This means choosing the kits to use with the project. Choose the kit(s) you created in the previous step, and then click Configure Project.

You can now build your project in Qt Creator on Linux.

3. Access services and content with an API key

API keys are permanent tokens that grant your application access to ready-to-use services and, with an ArcGIS Developer account, private content hosted in ArcGIS Platform (currently in beta). Your apps will always require an access token, such as an API key or OAuth 2.0 token, in order to access these resources. Refer to authentication methods in the developer guide for details.

To set an API key in your application, find and copy an API key from your developer dashboard and replace the string YOUR_API_KEY / ACCESS_TOKEN in your code with the API key copied from your dashboard. This key is scoped to provide access to all of the services and resources shown in the tutorials.

  1. Log in to your developer dashboard.
  2. Select and copy your default API key, or generate a new one.
  3. In your code, replace the string YOUR_API_KEY / ACCESS_TOKEN with the API key from your dashboard.

4. Tutorials

Deploy your app

No license is required to develop ArcGIS Runtime apps; there's no need to authorize your development machine or devices. As a member of the ArcGIS Developer Program, you have a free ArcGIS Developer Account (Essentials Plan). With this plan, you can download and install any ArcGIS API and immediately have access to all the functionality of the APIs for development purposes. You can become a member of the developer program for free.

You need an ArcGIS Developer Subscription to deploy an app to your users. The Essentials plan is free.

Learn more about Runtime licensing and deployment and get your license string at License and deployment.

Next steps

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.