# The AWS Graviton guide is a checklist of what actually changes when you move to Arm > This repository is AWS's own collection of guidance for running workloads on Graviton processors, from processor generation tables to per language notes, container advice, machine learning pages and a performance runbook. It is documentation rather than software, it has no releases, and its licence is a custom set of terms with separate files for sample code. **aws/aws-graviton-getting-started** — Helping developers to use AWS Graviton2, Graviton3, and Graviton4 processors which power the 6th, 7th, and 8th generation of Amazon EC2 instances (C6g[d], M6g[d], R6g[d], T4g, X2gd, C6gn, I4g, Im4gn, Is4gen, G5g, C7g[d][n], M7g[d], R7g[d], R8g). - Repository: https://github.com/aws/aws-graviton-getting-started - Website: https://aws.github.io/graviton/ - Stars: 1,063 · Forks: 232 - Language: Python - License: NOASSERTION - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/aws-aws-graviton-getting-started ## The processor table is the part worth reading twice Most of the repository is links, but the README opens with a dense comparison table of the Graviton generations, and it answers the questions a porting team actually has. The columns cover Graviton2, Graviton3 with its E variant, Graviton4 and Graviton5, and the rows run from instance families to core counts and cache sizes. The differences are not cosmetic. Graviton2 is Neoverse-N1 at 2500MHz on ARMv8.2-a, Graviton3 is Neoverse-V1 at 2600MHz on ARMv8.4-a, Graviton4 is Neoverse-V2 at 2800MHz on Armv9.0-a, and Graviton5 is Neoverse-V3 at 3300MHz on Armv9.2-a. The Cores row climbs from 64 to 64 to 96 per socket with 192 for the 48xlarge two socket part, and 192 for Graviton5. L2 cache per core doubles from 1MB to 2MB at Graviton4, and the shared last level cache moves from 32MB to 36MB to 48MB per NUMA node, with 96MB on the larger Graviton5 sizes. Two rows matter most for a port. The first is 32 bit backward compatibility, which is userspace only on Graviton2 and Graviton3 and has no support at all on Graviton4 and Graviton5, so a workload with a 32 bit binary stops working on the newer generations. The second is SIMD width, which is 2x Neon 128 bit vectors on Graviton2, 4x Neon or 2x SVE 256 bit on Graviton3, and 4x Neon or SVE 128 bit from Graviton4 onwards. ## The recommended compiler flag changes with the generation The table gives a recommended -mcpu value per generation, and this is the concrete instruction for anyone building native code. Graviton2 wants neoverse-n1, while Graviton3, Graviton4 and Graviton5 all want neoverse-512tvb. The README links the c-c++.md page for more information on enabling Arm architecture specific features. The c-c++.md page is where that flag is explained in full, and the repository goes further with a dedicated arm64-assembly-optimization.md page and a Software Optimization Guide reference per generation, which is Arm's own document giving instruction throughput and latency for each core. The SIMD_and_vectorization.md page covers the Advanced SIMD instructions, and the guide's point is that these are available as instructions rather than as a library call, so a tuned kernel on Graviton4 or Graviton5 has SVE2 and SVE with the int8, bf16 and bitperm extensions available. The alternative to the newest feature set is the older, wider instruction set. The table shows Graviton3 with 2x SVE 256 bit vectors where Graviton4 has 4x Neon or SVE 128 bit, so a kernel written for maximum vector width on one generation is not automatically the best on the next. That is the practical reason the guide also documents runtime detection, discussed below, rather than telling every team to hard code one target. ## HWCAPS is the answer when the target is not known until runtime The optimizing section names the problem directly. Different generations support different features, so Graviton3 supports SVE while Graviton2 does not, and Graviton4 and Graviton5 support SVE2 and SVE. For some applications the advice is to implement the performance critical kernels against the highest performing feature set available, and then notes the catch: that feature set may not be known until runtime. The prescribed solution is HWCAPS, the hardware capability register, and there is a dedicated runtime-feature-detection.md guide for working with it. The mechanism is that the program reads what the running CPU actually implements and dispatches to the right kernel, which turns a compile time target decision into a runtime one. It also removes the trap of shipping a binary built for neoverse-512tvb to a Graviton2 instance, where the table shows the RNG instructions and 32 bit compatibility story differ. Two more pieces of the same concern live in the repository. Monitoring_Tools_on_Graviton.md covers the profiling utilities, on the premise that some tools familiar from one architecture have no equivalent on Graviton, and the perfrunbook directory holds detailed checklists for optimizing and debugging performance rather than a single tuning guide. ## Per language notes are where the migration work actually lands The repository carries separate pages for C and C++, Go, Groovy, Java, .NET, Node.js, PHP, Python and Rust, each under its own file name at the repository root. There is also a page for PHP opcache on Amazon Linux 2, and a CommonNativeJarsTable.md that tracks native JAR dependencies, which is the kind of detail that decides whether a Java migration is a one line change or a week of work. Alongside the language pages there are the platform ones. os.md covers operating system support, linux_kernel.md covers the kernel, containers.md covers building and running containers on Graviton, and dpdk_spdk.md covers DPDK and SPDK datapath software. For a team moving an existing service, the practical sequence is the language page first, then the container page, then the known issues list. The AWS Lambda story has its own directory, aws-lambda/, and the repository also links a perfrunbook, a managed_services.md page listing AWS Managed Services available on Graviton, and an isv.md page on third party software vendors, which is the fastest way to find out whether the database or monitoring agent you depend on has an Arm build at all. ## Machine learning and analytics have their own pages A machinelearning directory holds separate documents for PyTorch, llama.cpp, TensorFlow, vLLM and ONNX, and DataAnalytics.md covers Spark on Graviton, while R.md covers R. This is the part of the guide with the most commercial weight, because Arm instances are usually adopted for inference and for data processing rather than for general purpose web serving. The pattern across the pages is the same one the CPU table implies. A build that assumed x86 specific instructions, or a dependency distributed only as an x86 wheel, has to be found and replaced, and the guide is where those cases are written down. The vLLM and llama.cpp pages matter for a self hosted inference service, and the PyTorch page matters for training jobs where a checkpoint written on one architecture is loaded on another. Two more directories complete the coverage. The HPC directory handles high performance computing, and a video-encoding directory sits at the repository root as well, which suggests a workloads based organisation of the guidance rather than a strictly CPU generational one. ## No releases, a custom licence, and a repository that keeps changing This is a documentation repository with no GitHub releases, and the version record is the commit history. The last push was on 2026-10-16, so the content is being revised, but there is no tagged edition you can pin a build against. The published site is at aws.github.io/graviton, which is where the rendered guide lives. The licence deserves attention because it is not a standard one. The repository root carries three separate files, LICENSE, LICENSE-SAMPLECODE and LICENSE-SUMMARY, which is the pattern of a project with different terms for different parts of its content, most likely the prose, the example code and a plain language summary of the obligations. GitHub does not classify the licence, so a team that copies sample code from sample-code/ should read LICENSE-SAMPLECODE specifically rather than assuming the same terms as the documentation. No legal reading is offered here; the point is that the three files are not interchangeable. The structure also includes a SUMMARY.md, which is the table of contents for a documentation tool such as mdBook or GitBook, and a tools/ directory described in the README as tools and agent skills, which suggests the guide is now partly packaged for automated agents to consume. ## Conclusion Treat this repository as a reference to read during a porting project rather than a dependency to install, and use the processor table to pick which Graviton generation your instance family actually is before you tune anything. It is not a substitute for measuring your own workload, since the perfrunbook directory gives checklists rather than results. If you only have one workload and it is portable, the cheaper path may be an existing x86 instance family instead of a port, and the instance list in the guide is the fastest way to see which families are Arm and which are not. ## FAQ ### What is the difference between Graviton3 and Graviton4 for porting purposes? Graviton3 is Neoverse-V1 on ARMv8.4-a at 2600MHz with 2x SVE 256 bit vectors, while Graviton4 is Neoverse-V2 on Armv9.0-a at 2800MHz with 4x Neon or SVE 128 bit vectors, 96 cores per socket and 2MB of L2 per core. Graviton4 also has no 32 bit backward compatibility support, while Graviton3 keeps it for userspace only. ### What compiler flag should I use for Graviton? The README's processor table lists neoverse-n1 as the recommended flag for Graviton2 and neoverse-512tvb for Graviton3, Graviton4 and Graviton5. The c-c++.md page explains the flag in full, and the perfrunbook directory holds the optimization checklists. ### How do I detect which CPU features are available at runtime on Graviton? The guide points to HWCAPS and links a dedicated runtime feature detection document, because the fastest available feature set depends on the generation and may not be known until the program runs. ### Is there a performance runbook for Graviton? Yes, the repository has a perfrunbook directory with detailed checklists for optimizing and debugging performance on Graviton, separate from the general debugging and profiling information in optimizing.md. The entries are checklists rather than benchmark results. ### What licence does the AWS Graviton guide use? GitHub cannot classify it as a standard licence, and the repository carries three separate licence files at the root: LICENSE, LICENSE-SAMPLECODE and LICENSE-SUMMARY. Sample code under sample-code/ should be checked against LICENSE-SAMPLECODE specifically. ## Sources - [aws/aws-graviton-getting-started on GitHub](https://github.com/aws/aws-graviton-getting-started) - [Issues](https://github.com/aws/aws-graviton-getting-started/issues) - [Project website](https://aws.github.io/graviton/) - [README](https://github.com/aws/aws-graviton-getting-started/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aws-aws-graviton-getting-started