They are the same format. No YAML parser looks at the file name, so nothing about the content parses differently. .yaml is the preferred extension and .yml is not wrong. The only thing that actually breaks is a tool that picks a filename for you, or a glob that matches one pattern and not the other.
Here is the parser half settled. One five-line document, copied to seven names, read by two implementations that share no code — PyYAML is a pure-Python scanner, Psych wraps the C libyaml:
$ cat body.txt
service:
name: api
ports:
- 8080
- 8443
PyYAML 6.0.2 Ruby 2.6.10 / Psych 3.1.0
config.yaml -> {'service': ...} config.yaml -> {"service"=>...}
config.yml -> identical config.yml -> identical
config.YAML -> identical config.YAML -> identical
config.json -> identical config.json -> identical
config.txt -> identical config.txt -> identical
config.exe -> identical config.exe -> identical
config -> identical config -> identical
All fourteen loads returned {'service': {'name': 'api', 'ports': [8080, 8443]}}. Both APIs take a stream or a string; the name never reaches the scanner. Python’s own mimetypes module on this machine does not even recognise the extensions — guess_type('x.yaml') and guess_type('x.yml') both return (None, None), while .json returns ('application/json', None).
Where the recommendation actually lives
The YAML 1.2.2 specification does not mention file extensions at all. Fetching yaml.org/spec/1.2.2/ and stripping the tags gave 166,180 characters of text on 2026-08-11; searching it for .yaml, .yml, “file extension”, “media type”, “MIME” and “IANA” returns zero matches for every one of those six terms.
The recommendation is in RFC 9512, the IETF registration of the application/yaml media type, published February 2024. Its registration template reads File extension(s): "yaml" (preferred) and "yml", and §3.3 says:
“The “yaml” filename extension is the preferred one; it is the most popular and widely used on the web. The “yml” filename extension is still used. The simultaneous usage of two filename extensions in the same context might cause interoperability issues (e.g., when both a “config.yaml” and a “config.yml” are present).”
That last clause is the entire practical risk, and it is about having both, not about choosing either.
The tools that do care
Not run here — no Docker, kubectl or GitHub runner on this machine — so these are quoted from each project’s own primary source:
- Docker Compose resolves a conflict silently. The Compose Specification: “The default path for a Compose file is
compose.yaml(preferred) orcompose.ymlthat is placed in the working directory. Compose also supportsdocker-compose.yamlanddocker-compose.ymlfor backwards compatibility of earlier versions. If both files exist, Compose prefers the canonicalcompose.yaml.” Four accepted names, one winner, no warning about the others. - kubectl accepts both but rejects everything else when
-fpoints at a directory. Ink8s.io/cli-runtime/pkg/resource/builder.go:var FileExtensions = []string{".json", ".yaml", ".yml"}, used to expand directory paths, with the failure message “recognized file extensions are %v”. A manifest saved asdeploy.txtin a directory is skipped without comment. - GitHub Actions accepts both: “Workflow files use YAML syntax, and must have either a
.ymlor.yamlfile extension”, stored in.github/workflows.
Your own globs are the likeliest culprit
This one is executable, and it is what usually bites in a Makefile, a linter invocation or a CI paths: filter:
$ ls
a.yaml b.yml
$ for f in *.yml; do echo "$f"; done
b.yml
$ for f in *.yaml; do echo "$f"; done
a.yaml
$ for f in *.y*ml; do echo "$f"; done
a.yaml
b.yml
Pick one extension per repository so this never comes up, prefer .yaml for new work, and leave an existing .yml project alone — renaming files costs more than it buys. If you must handle both, *.y*ml matches both and is what the third command above returned. The same five-line document under seven names, the mimetypes lookups and the three glob cases all run in yml-vs-yaml.sh, which, when online, also re-downloads the RFC 9512, Compose, kubectl and YAML 1.2.2 sources to check that what this page says about them still holds.
Then stop thinking about the extension. The things that actually corrupt a YAML config are inside the file: unquoted scalars getting a type you did not ask for, an empty key that is null rather than an empty list, and folded blocks that keep newlines you thought you had removed. Each of those is measured on its own page.
Not tested here: whether any specific version of Jenkins, Ansible or GitLab CI accepts an alternative extension for its own config file. The GitLab documentation I checked states the extension rule for include:d files but does not say whether .gitlab-ci.yaml works in place of .gitlab-ci.yml, so this page does not claim either way.