How to sort YAML keys alphabetically
To sort yaml keys, the tool reads the YAML into a tree, puts the keys of every map in order and writes the tree back. Values do not change. Only the position of each key does, and a key keeps its comments and its nested content with it.
Take a translation file:
menu:
settings: Settings
about: About
Home: Home
errors:
item10: Ten
item2: Two
item1: One
title: DashboardWith the default order it becomes:
errors:
item1: One
item10: Ten
item2: Two
menu:
Home: Home
about: About
settings: Settings
title: DashboardTwo things are worth noticing. Home came before about, because code point order puts capital letters first. And item10 came before item2, because the keys are compared as text. The next section shows how to change both.
Order: code point, ignore capitals or natural
- Code point order compares characters by their code, so A to Z come before a to z. It matches how most programming languages sort strings, which makes it the best choice when a script or another tool must produce the same order.
- Ignore capitals treats A and a as the same letter, which is how people expect a list to read.
- Natural order reads digit runs as numbers, so item2 comes before item10. It also ignores capitals.
Direction can be ascending or descending. Levels decides whether every map is sorted or only the outermost one. For a Helm values file, sorting only the top level keeps the sections in order without touching each section inside.
Keep apiVersion and kind first in Kubernetes files
A strictly alphabetical Kubernetes manifest puts apiVersion, kind, metadata and spec in an order readers do not expect. The Key order preset handles this. With Kubernetes selected, the top level starts with apiVersion, kind, metadata and spec, and inside metadata the keys start with name, namespace, labels and annotations. Everything else is sorted as usual.
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
namespace: shop
labels:
app: web
tier: frontend
spec:
replicas: 2That is the top of the result for the built-in sample. There are presets for OpenAPI, Docker Compose and GitHub Actions too, and Pin keys first accepts your own list, such as name,version. Pinned names apply to each top-level map and are written in the order you give.
Do comments survive sorting?
Yes. A comment at the end of a line stays on that line with its key. A comment on the line above a key moves with that key, so the explanation still sits above what it explains. A comment at the very top of the file followed by a blank line stays at the top of the file.
A comment directly above the first key, with no blank line between, belongs to that key, and it moves with it. If you want a header that never moves, add a blank line after it.
The tool writes the YAML again, so some formatting is normalized. Indentation follows your choice of 2 or 4 spaces, quote styles and block scalars are kept, and long lines are not wrapped. A folded > block may be rejoined onto one line, which means the same text. Blank lines between keys are not always kept. Check the diff before you commit.
Anchors, aliases and merge keys
Anchors (&name) and aliases (*name) are not expanded. They stay in the file as they were. A merge key such as << stays first inside its map, which is where people expect to find it.
YAML needs an anchor to appear before the alias that uses it. Sorting can break that, for example when the key holding the anchor sorts after the key using the alias. The tool does not write invalid YAML. It stops and tells you which anchor is the problem. Pin the key that holds the anchor so it stays first.
Files with several documents
Kubernetes files often hold several documents separated by ---. Each document is sorted on its own, and the separators are kept. The notes say how many documents were found. An empty document, such as a trailing ---, is skipped.
Lists, repeated keys and limits
- Lists keep their order by default, because the order of items often matters, as in a list of steps. Set Lists to Sort plain values to sort lists that hold only text or numbers. Numbers sort by value, so 9 comes before 10. Lists of maps are never reordered, but the keys inside each map are sorted.
- A key that appears twice in one map is reported in the notes. Both copies are kept in their original order, and YAML tools differ on which one wins, so fix the source.
- Does key order matter in YAML? For maps, no: a YAML reader treats two maps with the same keys as equal. Some tools do show or preserve order, and a stable order makes diffs easy to read, which is the reason to sort.
- Values are written exactly as you typed them. 0644, 1e3, +1 and 0x1F stay as they are, so a Kubernetes file mode is not turned into a different number.
- Input over 250,000 characters is refused with a message, because sorting runs inside the page and a larger file would freeze it. Very deep nesting, over 400 levels, is refused too.
Related tools: Sort JSON Keys for JSON, YAML to JSON and JSON to YAML to switch formats, and Sort Lines for plain lines of text.
Privacy
Config files can hold hostnames and secrets. The sorting runs in your browser and the YAML is not uploaded. The Privacy Policy explains what the site stores. Replace real secrets with placeholders before you share a file.