.yml vs .yaml File Extension – Is There a Difference?

Updated

.yml vs .yaml file extension

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) or compose.yml that is placed in the working directory. Compose also supports docker-compose.yaml and docker-compose.yml for backwards compatibility of earlier versions. If both files exist, Compose prefers the canonical compose.yaml.” Four accepted names, one winner, no warning about the others.
  • kubectl accepts both but rejects everything else when -f points at a directory. In k8s.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 as deploy.txt in a directory is skipped without comment.
  • GitHub Actions accepts both: “Workflow files use YAML syntax, and must have either a .yml or .yaml file 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.

Photo of author
Sudhir P. founded HeatWare.com in 1999 and has built and operated it full-stack ever since; it is now used by more than 88,000 people. He writes here about the PostgreSQL, MySQL, Linux and DevOps work that keeps it running. Articles are rewritten only after the commands in them have actually been run, and the verification scripts are published alongside them so anyone can check the claims. Reach him at blog@heatware.net.