Last updated: April 28, 2026
.yml vs .yaml: Are They the Same?
The short answer is yes. The slightly longer answer covers history, tool conventions, and the YAML organization's official recommendation.
Written by Mohan Raj Kolavi.
Quick answer: .yml vs .yaml
They are the same. Both extensions identify a YAML file. Every parser accepts either. The official YAML organization recommends .yaml, but .yml remains common because of legacy three-letter file extension limits on early Windows systems. Use .yaml for new files; leave existing .yml files alone.
Why are there two extensions?
YAML was first proposed in 2001. At the time, common Windows file systems limited file extensions to three characters, so the shorter .yml was widely adopted. With YAML 1.2 (2009) the YAML organization standardized on .yaml as the preferred extension and added it to the official spec.
Both extensions are still in active use. The choice today is mostly cultural - some ecosystems lean to .yml(Ruby, Rails, Docker Compose), others to .yaml(Kubernetes, OpenAPI, GitHub Actions in newer docs).
The YAML org's recommendation
The yaml.org FAQ states that .yaml is the preferred extension. The reason is brand consistency - the format is spelled YAML, so the file extension should match. There is no technical difference: every YAML parser registers both extensions in its file-detection logic.
Tool support matrix
| Tool | Accepts .yml | Accepts .yaml | Convention |
|---|---|---|---|
| Kubernetes (kubectl) | Yes | Yes | .yaml |
| GitHub Actions | Yes | Yes | .yml (legacy) |
| Docker Compose | Yes | Yes | .yml (legacy), .yaml (newer) |
| Ansible | Yes | Yes | .yml |
| Ruby on Rails | Yes | Yes | .yml |
| OpenAPI / Swagger | Yes | Yes | .yaml |
| GitLab CI | Required (.gitlab-ci.yml) | No (filename fixed) | .yml |
| CircleCI | Required (config.yml) | No (filename fixed) | .yml |
| Helm charts | Yes | Yes | .yaml |
| Hugo / Jekyll front matter | N/A (embedded) | N/A (embedded) | N/A |
When the extension is fixed
A handful of tools require a specific filename, not just a specific extension. Examples:
.gitlab-ci.yml- GitLab CI looks for this exact filename in the repo root..circleci/config.yml- CircleCI looks for this exact path.docker-compose.ymlorcompose.yaml- Docker Compose accepts both, but only those exact names..travis.yml- Travis CI looks for this exact name.
In these cases the filename is part of the tool's configuration contract. Do not rename them.
Practical recommendation
- Match the tool. If the docs or examples use one extension consistently, follow that.
- Match the repo. If existing files use one extension, keep it consistent for new files.
- Otherwise default to .yaml. The YAML organization recommends it, and it disambiguates the format name.
- Do not mass-rename. Renaming
.ymlfiles in a large repo can break CI scripts that hardcode filenames. Leave them alone unless there is a specific reason to switch.
Next steps and related guides
- Complete YAML guide - what YAML stands for, syntax, file format basics.
- YAML vs JSON - feature-by-feature comparison.
- YAML validator - check any .yml or .yaml file for syntax errors.
- YAML formatter - normalize indentation and produce diff-clean output.
Frequently Asked Questions
Is .yml the same as .yaml?
Yes. Both extensions identify the same file format - YAML. Every parser that reads .yaml also reads .yml. The content rules, indentation, and syntax are identical.
Which extension should I use - .yml or .yaml?
The official YAML organization recommends .yaml. The .yml extension is a historical Windows-era three-letter shortening that stuck in some ecosystems (Ruby, older Java, Docker Compose). Use .yaml for new files unless your tool requires .yml.
Why are there two extensions for YAML?
Early Windows file systems limited extensions to three characters, so .yml was used. After YAML 1.2 (2009), the YAML community standardized on .yaml. The two extensions coexist for backward compatibility, and most tools now accept either.
Does Kubernetes care if I use .yml or .yaml?
No. kubectl reads files by content, not by extension. Both kubectl apply -f deploy.yml and kubectl apply -f deploy.yaml work. The community convention for Kubernetes is .yaml.
Does GitHub Actions need .yml or .yaml?
GitHub Actions accepts both .yml and .yaml in the .github/workflows directory. Historically, GitHub examples use .yml, so most existing workflows are named workflow.yml.
Does Docker Compose require .yml?
Docker Compose accepts both. Older docs and the default file name convention use docker-compose.yml, but compose.yaml is also recognized and is the newer convention.
Will switching from .yml to .yaml break my project?
Almost never. The only risk is build scripts or CI configs that explicitly look for one extension. Search your repo for the literal string .yml or .yaml before renaming and update any hardcoded paths.
What does YAML stand for?
YAML originally stood for 'Yet Another Markup Language' but was redefined as 'YAML Ain't Markup Language' to clarify that it is a data serialization format rather than a markup language like XML or HTML.
Are .yml and .yaml MIME types different?
The official IANA-registered MIME type is application/yaml (registered in 2024). Older tools may serve YAML as text/yaml or text/x-yaml. The MIME type is independent of the file extension.
Should I convert all my .yml files to .yaml?
No. There is no functional benefit, and a mass rename can break CI scripts that look for specific filenames. Use .yaml for new files; leave existing .yml files alone unless you have a specific reason to rename them.