Getting started with Graviton

Adopt Graviton-based instances for your workloads with this step-by-step guide

Graviton Getting Started Guide

AWS Graviton processors are custom designed by AWS to enable the best price performance for workloads in Amazon EC2. Amazon EC2 instances powered by AWS Graviton2 processors provide up to 40% better price performance over comparable fifth generation x86-based instances for a wide variety of workloads. The latest AWS Graviton3 processors add significant performance improvements over Graviton2, providing 25% better performance for a wide range of workloads.

We have seen many customers adopt Graviton with minimal effort and continue to enjoy significant price-performance benefits. This guide outlines a framework to help you quickly move your own workload to Graviton-based EC2 instances with ease, all based on the best practices we’ve found from working with thousands of customers.

This plan is designed so a single engineer or small team can accomplish all four steps, with each step split into two subtasks.

This 4-step plan is suitable for many applications, but based on the complexity of your application, some migrations take more time and others less. Regardless of the application complexity, the approach and high-level steps described here remain the same.

Get started for free with Amazon EC2 T4g Instances powered by Graviton2 processors. Free for up to 750 hours per month until Dec 31st 2023. Check out the free tier FAQs page for more details.

 AWS experience


 Time to complete

4 hours. Infrastructure provisioning times may vary.

 Cost to Complete

Depends on Infrastructure choices made during deployment. See EC2 and component pricing to estimate cost.


You must be logged into an AWS account.

 Last updated

March 22, 2023

 Get started

How to identify a good target workload

A good candidate for Graviton adoption is a workload running on Linux or BSD, built either using open-source components or source code that you control. Having full access to the source code of every component allows you to make any necessary changes quickly and easily as part of this adoption plan. If you use third-party software, many ISVs already support the Arm64 architecture implemented by AWS Graviton processors.

Steps to migrate your workload to Graviton

  • Task 1: Review key documentation and software support for Graviton

    Start by watching these two demos which will give you an overview of the Graviton-based instances and some insights on how to run applications depending on their operating system, languages, and runtimes.  

    AWS re:Invent 2022 - AWS Graviton deep dive: The best price performance for AWS workloads
    re:Invent 2021 – Deep dive into AWS Graviton3 and Amazon EC2 C7g instances

    Keep learning about silicon innovation to better understand Amazon’s commitment to pushing the envelope with custom silicon.  

    re:Invent 2021 – The journey of silicon innovation at AWS

    And spend some time reading relevant sections of the Getting started with AWS Graviton repository on GitHub, which will act as a useful reference throughout your adoption.

    Task 2: Explore your workload, and inventory your current software stack

    Top Tip

    Task 2 will require you to build the application/workload list of dependencies. If you need information from other teams, it might be useful to ask them for this information before you start the first task, so that you could have their answers by the time you reach Task 2.

    To start the migration, the first thing you need to do is inventory your current software stack so you can identify the path to equivalent software versions that support Graviton. At this stage, it can be useful to think in terms of software you download (e.g. open source packages, container images, libraries), software you build, and software you procure/license (e.g. monitoring or security agents).

    Areas to review:

    • Operating system and version (the more recent the better).
    • If your workload is container based, check container images you consume for Arm64 support. Keep in mind many container images now support multiple architectures, which simplifies consumption of those images in a mixed-architecture environment. You can read ECR multiarch support announcement for more details.
    • All the libraries, frameworks, and runtimes used by the application and its components.
    • The tools used to build, deploy, and test your application (e.g. compilers, test suites, CI/CD pipelines, provisioning tools, and scripts).
    • All the tools and/or agents used to deploy and manage the application in production (e.g. monitoring tools or security agents).

    There are language-specific sections in the getting started guide with useful pointers to get the best performance from Graviton processors as well as guidance for Operating Systems, Container environments, and various open-source software.

    For each component of your software stack, check the version and then check whether they are available for Graviton/Arm64. AWS Graviton processors are modern processors and to benefit from their full potential, it is generally recommended to use software versions that are as recent as possible. As an example, Java 8 works perfectly well on Graviton, but we’ve seen several applications benefiting from upgrading to Java 11 due to Arm64-specific optimizations in Java 11 (refer to the Getting started with AWS Graviton repository for details on how to get the best performance on Graviton). It is also worth noting that it is generally simpler to upgrade the dependencies first on x86-64, and then transition to Graviton with the most recent versions of software already in place to reduce the number of variables.

    Depending on where you obtain your dependencies, there could be multiple ways to check whether they support Graviton. Some tools, like GCC, call the architecture AArch64, and some others, like the Linux Kernel, call it Arm64. When looking for packages in the various repositories, you’ll find those different combinations, and sometimes just “ARM.”

    If you find any software without support for the Arm64, please let AWS know by reaching out on the re:Post community support forum.

    The main ways to check and places to look include:

    • The package repositories of your favorite Linux distributions. The coverage is generally rather comprehensive: Debian, for example has some of the largest package repositories with more than 98% of its packages built for the Arm64 architecture, and of the remaining 2%, some are x86 specific or games that are not typically used in a server environment.
    • Your container image registry. Amazon ECR now offers public repositories that you can search for Arm64 images. DockerHub allows you to search for a specific architecture (Arm64 enabled images).  

    Specific to containers you may find an amd64 (x86-64) container image you currently use has become a multi architecture container image when Arm64 support was added meaning there may not be an explicit Arm64 container, so make sure you check for both as different projects may choose different ways to vend their container images for both x86-64 and Arm64.

    • On GitHub, you can check for Arm64 versions in the release section. However, some projects don’t use the release section or only release source archives, so you may need to visit the main project webpage and check the download section. You can also search the GitHub project for “Arm64” or “AArch64” to see whether the project has any Arm64 code contributions or issues. Even if a project does not currently produce builds for Arm64, in many cases, an Arm64 version of those packages will be available through Linux distributions or additional package repositories (e.g. EPEL). You can search for packages using a package search tool, such as
    • In the download section or platform support matrix of your software vendors, look for references to Arm64, AArch64, or Graviton. Software vendor documentation will often list ‘platform requirements’ which include supported operating system versions and architectures.

    Categories of software with potential issues:

    • Packages or applications sourced from independent software vendors (ISV’s) may not exist for Graviton yet. However, AWS is working with lots of software partners to offer technical guidance to port and optimize their software on Graviton, so the list of available ISV software continues to expand.
    • The Python community often produce modules containing low level language code (e.g. C/C++) that needs to be compiled for the Arm64 architecture prior to use on Graviton. While AWS is actively working with the open-source community to ensure the most popular modules are available, in some cases the Python Package Index may lack pre-built binaries for Arm64. To avoid falling back to sub-optimal pure Python versions these modules can automatically be built from source code (See the Python section of the re:Post community support forum for details).
  • Task 3: Install and configure your application environment

    To transition and test your application, you will first need a Graviton environment, so depending on your execution environment, you’ll have to:

    • Obtain or create an Arm64 AMI to boot your Graviton instance(s) from. Depending on how you manage your AMIs, you can either start directly from an existing reference AMI for Arm64, or you can build your Golden AMI with your specific dependencies from one of the reference images. See reference list here.
    • If you operate a container-based environment, you’ll need to build or extend an existing cluster with support for Graviton-based instances. Both Amazon ECS and EKS support adding Graviton-based instances to an existing x86-based cluster. For ECS, you just need to add Graviton-based instances to your ECS cluster, launching them with either the AWS ECS optimized AMI for Arm64 or your own AMI after you’ve installed the ECS agent. For EKS, you will need to create a node-group with Graviton2-based instances launched with the EKS optimized AMI for Arm64.

    You can support Graviton and x86 instances in the same Auto Scaling Group using the launch template override.

    • Complete the installation of your software stack based on the inventory created in Task 2.

    Task 4: Build your application(s) and/or container images

    Note: if you are not building your application or component parts of your overall application stack, then you may skip this step.

    Now that you have an environment available, you can build your application stack. For applications built using interpreted or JIT languages, including Java, PHP, or Node.js, they should run as-is or with only minor modifications. The repository contains language-specific sections with recommendations such as:

    Note: if there is no language specific section, it is because there is no specific guidance beyond using a suitably current version of the language relevant to Graviton (e.g. PHP Version 7.4+). .NET-core is a great way to benefit from Graviton-based instances, for example, .NET5 performance.

    Applications using compiled languages, including C, C++, or Go, need to be compiled for the Arm64 architecture. Most modern builds (e.g. using Make) will work when run natively on Graviton-based instances, however, you’ll find language-specific compiler recommendations in the repositories.

    Just like an operating system, container images are architecture-specific. You will need to build Arm64 container image(s). To make the transition easier, we recommend building multi-arch container image(s) that can run automatically on either x86-64 or Arm64. Check out the container section of the repository for more details and this detailed overview of multi-architecture container image support, which is considered a best practice for establishing and maintaining a multi architecture environment.

    If you believe you are observing architecture-specific issues, please check the Arm Architecture Reference Manual Armv8 or reach out to us on the re:Post community support forum.

    You will also need to review any functional and unit test suite(s) to ensure you can test the new build artifacts with the same test coverage you have already for x86 artifacts.  

  • Task 5: Testing and optimizing your workloads

    Now that you have your application stack on Graviton, you should run your test suite to ensure all regular unit and functional tests pass. Resolve any test failures in the application(s) or test suites until you are satisfied everything is working as expected. Most errors should be related to the modifications and updated software versions you have installed during the transition. If you suspect architecture-specific issue(s) please have a look at the C/C++ section in Task 4, which documents them and gives advice on how to solve them. If there are still details that seem unclear or you are not observing the expected application performance, reach out to us on the re:Post community support forum.

    When upgrading software versions, first test them using an existing x86 environment to minimize the number of variables changed at a time. If issues occur, then resolve them using the current x86 environment before continuing with the new Graviton environment.

    Task 6: Performance testing

    With your fully functional application, it’s time to establish a performance baseline on Graviton. In most cases, you should expect performance gains. When comparing to existing x86-64 instances, we recommend running tests by fully loading both systems to determine the maximum possible price/performance. You can then determine and configure an appropriate load level for your production environment before performing the deployment.

    Important: This repository has sections dedicated to Optimization and a Performance Runbook for you to follow during this stage.

    If, after reading the documentation in this repository and following the recommendations, you do not observe expected performance, then please reach out to your AWS account team, or send an email to with details so we can assist you with your performance observations.

  • Task 7: Update your infrastructure as code

    Now that you have a tested and performant application, it’s time to update your infrastructure as code to add support for Graviton-based instances. This typically includes updating instance types, AMI IDs, ASG constructs to support multi-architecture (see Amazon EC2 ASG support for multiple Launch Templates), and finally deploying or redeploying your infrastructure.

    Task 8: Perform Canary or Blue-Green deployment

    Once your infrastructure is ready to support Graviton-based instances, you can start a Canary or Blue-Green deployment to re-direct a portion of application traffic to the Graviton-based instances. Ideally, you’ll run these initial tests in a development environment and load test with traffic patterns as close as possible to production traffic. Monitor the situation carefully to catch any unexpected behavior until your application is running as expected on Graviton, at which point you can determine your transition strategy.


Now that you have completed your first application migration to Graviton by following the 4-step plan. We understand this project took significant effort and time, and hope you were able to benchmark price performance benefits by using Graviton-based instances for your workloads. We’d love to hear about your experience on the re:Post community support forum.

This is just the beginning of your Graviton adoption journey. If you realized significant price performance gains with your first workload, you can identify more workloads from different AWS services and get even more price performance gains in AWS.

Explore more of AWS