Yes. A .yaml file and a .yml file contain exactly the same format, and any YAML parser reads both the same way. The YAML vs YML difference is only the extension: .yaml is the officially preferred spelling, and .yml is a common short form that most tools also accept.
YAML vs YML: what is actually different?
Nothing inside the file is different. The extension is a label for people and tools; the parser only looks at the text. The IETF's RFC 9512, which registered the application/yaml media type in February 2024, lists both extensions for that one type: "yaml" as preferred and "yml" as still used.
Copy settings.yml to settings.yaml and indentation, comments, anchors and quoting all behave identically. For a refresher on those rules, my comparison of JSON vs YAML for config files covers where YAML bites.
Why does the .yml extension exist?
The .yml spelling is usually explained as a habit from old systems that only allowed three-character file extensions. That's the common explanation in the long-running Stack Overflow thread on .yaml vs .yml, the same reason you still see .htm and .jpg. That limit is long gone. The convention stuck anyway.
Which extension is official?
The official recommendation is .yaml. RFC 9512 section 3.3 says the "yaml" extension "is the preferred one; it is the most popular and widely used on the web," while noting that "yml" is still in use. The same Stack Overflow thread quotes the yaml.org FAQ asking people to use .yaml when possible, a recommendation one answer dates back to 2006.
RFC 9512 also tidied up the media type. It registers application/yaml and lists application/x-yaml, text/yaml and text/x-yaml as deprecated aliases that are used but not registered. If you serve YAML over HTTP, send application/yaml.
How popular tools treat the two extensions
Most tools accept both, but some look for one exact filename first. Here is what the official docs say for two common ones:
| Tool | What it accepts | Preferred |
|---|---|---|
| Docker Compose | compose.yaml, compose.yml, plus docker-compose.yaml and docker-compose.yml for older setups |
compose.yaml |
| GitHub Actions | Workflow files with a .yml or .yaml extension in .github/workflows |
Either |
| Any YAML parser | Text, whatever the file is called | Not applicable |
Docker's documentation says the default path is compose.yaml (preferred) or compose.yml in the working directory. It also says that if both files exist, Compose prefers the canonical compose.yaml. GitHub's workflow syntax docs say workflow files "must have either a .yml or .yaml file extension."
When the extension does matter
The extension matters when a program searches for a specific filename instead of parsing whatever you hand it. Docker Compose is the clear example. Say a repo has an old compose.yml and someone adds a new compose.yaml while testing. Running docker compose up now picks compose.yaml, and the services you edited in compose.yml silently stop applying.
RFC 9512 warns about exactly this. Using both extensions "in the same context might cause interoperability issues," and its example is a folder holding both a config.yaml and a config.yml. A loader that checks one name first will never see the other file.
A few other places to check before you rename:
- Scripts and CI steps that pass a path like
-f deploy.yml. - Imports and includes that reference another YAML file by name.
- Editor and linter settings that match files with a glob such as
*.ymlonly. - Documentation that tells people which file to edit.
Which one should you use?
Use .yaml for new projects, and match the existing convention in old ones. .yaml is the better default: the RFC and the YAML project both prefer it, and Docker now names it first. Don't rename a working .yml file for style, though. A broken CI job costs more than the extra letter is worth.
My rule:
- New repo, no constraints: use
.yaml. - Existing repo: use whatever most files already use.
- A tool's docs show one name: use that name exactly.
- Never keep both
name.yamlandname.ymlin one folder.
The limitation: the extension tells you nothing about which YAML version or parser a file targets. A .yaml file can still trip over older parser quirks, like an unquoted no turning into a boolean.
Checking a YAML file whatever its extension
Because the extension doesn't change the format, you can check either kind of file the same way. Open it as text, copy the contents, and run it through a parser. If you need the data as JSON, OnlineViewer Dev has converters in both directions; the JSON to YAML converter runs in the page, so pasted config isn't sent to a server.
Converting is also a quick way to spot indentation mistakes. If a key ends up nested under the wrong parent in the JSON output, the YAML indentation is off. For the JSON side, what the JSON format allows and JSON vs JSON5 vs JSONC explain why the output looks stricter than your YAML.
FAQ
Is .yml or .yaml the official extension?
RFC 9512, the YAML media type registration from February 2024, lists "yaml" as the preferred extension and "yml" as still in use. The yaml.org FAQ also asks people to use .yaml when possible.
Can I rename a .yml file to .yaml?
Yes, the content doesn't change. Check first whether a tool looks the file up by its exact name, and update any scripts, CI steps or imports that refer to the old name.
Does Docker Compose read compose.yml?
Yes. Docker's docs say the default Compose file is compose.yaml (preferred) or compose.yml, and that docker-compose.yaml and docker-compose.yml still work for backwards compatibility. If both compose files exist, Compose prefers compose.yaml.
Do GitHub Actions workflows need .yml?
No. GitHub's docs say workflow files must have either a .yml or a .yaml extension and must live in the .github/workflows directory.