.yml vs .yaml

.yml and .yaml are two file extensions for the same format. A parser does not care which one you use. The official recommendation is .yaml, but many popular tools standardized on .yml years ago, so both are everywhere. Here is where the two came from and what each major tool expects.

The short answer

• Prefer .yaml for new files. It is the extension recommended by the YAML maintainers.
• Follow the tool's convention when a tool looks for a specific file name.
• Be consistent within a project. Mixing both is harmless but looks careless.

Why two extensions exist

YAML was created in 2001. At that time, Windows and some other systems still had strong conventions around three-character extensions, so .yml appeared alongside .yaml the same way .htm appeared alongside .html. Once those limits disappeared, the YAML project settled on .yaml as the recommended extension, but by then several influential tools had already shipped with .yml defaults and never changed them.

What popular tools expect

Tool	Expected file	Notes
Docker Compose	compose.yaml	Also accepts compose.yml, docker-compose.yaml, docker-compose.yml
Kubernetes	Any	kubectl apply -f accepts .yaml, .yml, and .json
GitHub Actions	.github/workflows/*.yml or *.yaml	Both discovered automatically
GitLab CI	.gitlab-ci.yml	Fixed name, .yml
Travis CI	.travis.yml	Fixed name, .yml
CircleCI	.circleci/config.yml	Fixed name, .yml
Ansible	Any	Community style guide recommends .yml
Helm	Chart.yaml, values.yaml	Fixed names, .yaml
OpenAPI / Swagger	openapi.yaml	Convention, either works
Home Assistant	configuration.yaml	Fixed name, .yaml
Ruby on Rails	config/database.yml	Fixed names, .yml
pnpm	pnpm-lock.yaml	Fixed name, .yaml

Editor and tooling support

Every mainstream editor associates both extensions with YAML syntax highlighting, and language servers such as the Red Hat YAML extension for VS Code recognize both. Linters like yamllint check both by default. You will not lose any tooling by choosing either one.

Making the switch in a project

1. Search for hard-coded references: grep -r "\.yml" . across scripts, Dockerfiles, CI config, and documentation.
2. Rename files with git mv so history is preserved.
3. Update the references you found and run your CI pipeline.
4. Validate each renamed file with the YAML validator to make sure nothing was corrupted during the move.

Whichever extension you pick, the content follows the same rules. If you are new to the format, start with YAML vs JSON for an overview of the syntax.