.yaml vs .yml — Is There Actually a Difference?

Q: Does `.yml` break in Kubernetes?

No. Kubernetes accepts both `.yaml` and `.yml` extensions. The `kubectl apply -f file.yml` command works fine with either extension. However, the Kubernetes ecosystem convention is strongly `.yaml` — all official documentation, examples, and tutorials use `.yaml`. Helm specifically requires `values.yaml` (not `values.yml`) for its default configuration file. Using `.yml` in a Kubernetes project works but looks inconsistent with the broader ecosystem.

Every developer who starts working with YAML eventually asks this question:

Should I use .yaml or .yml?

The short answer is no — there is no functional difference. YAML parsers read both extensions identically. The YAML specification itself does not mandate either one.

But the long answer is more nuanced. The extension you choose affects:

how your editor highlights syntax
how your CI/CD platform detects file types
how your team's conventions evolve
how your project integrates with the wider ecosystem

This guide covers the history, the tooling implications, the ecosystem conventions, and the practical choice most teams make — along with the edge cases where the extension genuinely matters.

The History: Why Two Extensions Exist

Windows 8.3 Naming Convention

The original reason for .yml is purely technical: old Windows filesystems (FAT) imposed an 8.3 filename limit — eight characters for the name, three for the extension.

"YAML" is four characters, leaving only three for the extension. Hence .yml.

Windows 95, Windows NT, and modern Windows filesystems all support long filenames. But the three-letter extension stuck.

The YAML Specification

The YAML specification (both 1.1 and 1.2) uses .yaml in all official examples and recommends it as the preferred extension. The FAQ explicitly states:

"We recommend using .yaml in preference to .yml, but both are acceptable."

That is the official position. But the spec also acknowledges that .yml is widely used and will not go away.

Ecosystem Conventions: Who Uses Which

Kubernetes

Kubernetes overwhelmingly uses .yaml.

kubectl apply -f deployment.yaml

Every official Kubernetes example, every tutorial, every book, every KubeCon talk uses .yaml. The kubectl explain command outputs YAML headers with .yaml references. Helm charts use .yaml for templates and values.yaml.

If you work with Kubernetes, the ecosystem convention is .yaml. Using .yml in a Kubernetes context looks wrong to experienced operators.

Docker Compose

Docker Compose uses docker-compose.yml (or compose.yml in newer versions).

docker compose -f docker-compose.yml up

The official Docker documentation uses .yml. This is the most influential holdout for the three-letter extension.

If you use Docker Compose heavily, .yml is the convention and switching to .yaml will confuse team members.

GitHub Actions

GitHub Actions uses .yml.

# .github/workflows/deploy.yml

GitHub's workflow documentation, templates, and marketplace all use .yml. The GitHub web editor creates files with .yml by default. Renaming them to .yaml still works — the platform detects YAML content regardless of extension — but it goes against the established convention.

Ansible

Ansible uses .yml.

ansible-playbook playbook.yml

Ansible's documentation, examples, and community roles all use .yml. The ansible-lint tool recognizes .yml and .yaml but the convention is .yml.

GitLab CI

GitLab CI uses .yml.

# .gitlab-ci.yml

Same story — the convention is .yml and the platform creates files with that extension by default.

CircleCI

CircleCI uses .yml.

# .circleci/config.yml

Tooling Behavior Differences

File Detection

Some tools use file extension for type detection:

VS Code — treats .yaml and .yml identically. Syntax highlighting works for both.

Prettier — formats both extensions by default. No configuration needed.

yamllint — processes both extensions normally.

GitHub language detection — identifies both as YAML.

Schema Association

Some YAML schema tools only auto-detect schemas for .yaml files:

# Without schema: generic YAML highlighting
# With schema: Kubernetes-aware autocomplete

The Red Hat YAML VS Code extension associates schemas based on filename patterns. A file named deployment.yaml might auto-detect the Kubernetes schema. A file named deployment.yml might not — depending on your configuration.

This is configurable, but the defaults often favor .yaml.

Prettier and ESLint

Prettier formats both extensions. But if your .prettierignore or ESLint configuration explicitly targets file patterns, the extension matters:

# .prettierignore
*.yaml

This ignores .yaml but not .yml. If your team uses both extensions, you need both patterns.

The Practical Choice

After surveying the ecosystem, here is the pragmatic recommendation:

Use .yaml for most files. It is the spec-recommended extension, supported everywhere, and increasingly used by newer tools.

Use .yml for Docker Compose, Ansible, GitHub Actions, GitLab CI, and CircleCI files. These platforms have established .yml conventions. Going against the convention creates friction — new team members will look for docker-compose.yml not docker-compose.yaml, and CI/CD platform defaults will not auto-detect your files.

For everything else — Kubernetes manifests, application configuration files, data files, custom tooling — use .yaml.

This is a practical compromise, not a purity contest. Consistency within a project matters more than the specific extension.

When the Extension Actually Matters

Case 1: Kubernetes with Helm

Helm expects values.yaml (not values.yml). If you rename it, helm install will not find it.

# Works
helm install myapp ./chart --values ./chart/values.yaml

# Does not find the file
helm install myapp ./chart --values ./chart/values.yml

Case 2: Docker Compose Auto-Detection

Docker Compose auto-detects files named compose.yaml, compose.yml, docker-compose.yaml, and docker-compose.yml. If you name your file services.yaml, you must pass it explicitly:

docker compose -f services.yaml up

Case 3: GitHub Actions Workflow Detection

GitHub Actions only recognizes workflow files in .github/workflows/ with .yml extension. If you use .yaml, GitHub ignores the file.

This is the one case where the extension genuinely breaks functionality. Always use .yml for GitHub Actions.

Case 4: Static Analysis and Linters

Some static analysis tools use extension-based rules. A tool configured to only check *.yaml files will miss *.yml files and vice versa. If your CI pipeline enforces YAML formatting, ensure the glob pattern covers both extensions or standardize on one.

Migration: Renaming Between Extensions

If you decide to switch from .yml to .yaml (or vice versa), the migration is straightforward:

# Rename all .yml to .yaml (PowerShell)
Get-ChildItem -Recurse -Filter "*.yml" | Rename-Item -NewName { $_.Name -replace '\.yml$', '.yaml' }

After renaming:

Update any file references in your codebase
Update CI/CD pipeline file paths
Update Docker Compose commands
Update documentation references
Commit in a dedicated pull request (not mixed with other changes)

The main risk is forgetting to update a reference somewhere. grep your entire codebase for the old extension pattern:

grep -r "\.yml" --include="*.{yaml,yml,json,md,sh}" .

What the Community Thinks

The YAML community has surprisingly strong opinions about extensions.

Pro .yaml:

Spec-recommended
More explicit (four-letter format, four-letter extension)
Increasingly used by modern tools
Consistent with Kubernetes ecosystem

Pro .yml:

Shorter to type
Historically dominant in CI/CD
Docker Compose convention
"It does not matter, so stop arguing about it"

Most large open-source projects standardize on one extension internally. Kubernetes uses .yaml. Homebrew formula use .yaml. The CNCF ecosystem leans .yaml.

But Docker Compose, GitHub Actions, and Ansible are too entrenched in .yml to change.

FAQ

What is the difference between `.yaml` and `.yml`?

There is no functional difference — both extensions are valid YAML file extensions and all YAML parsers read them identically. The .yml extension originated from Windows 8.3 filename limitations (eight characters for the name, three for the extension). The YAML specification recommends .yaml but explicitly accepts both. The practical difference is ecosystem convention: Kubernetes, Helm, and general application configs use .yaml; Docker Compose, GitHub Actions, Ansible, GitLab CI, and CircleCI use .yml.

Should I use `.yaml` or `.yml`?

Use .yaml for Kubernetes manifests, application configuration, and custom tooling. Use .yml for Docker Compose, GitHub Actions workflows, Ansible playbooks, GitLab CI pipelines, and CircleCI configurations — these platforms have established .yml conventions that auto-detect files by extension. Consistency within a project matters more than the specific choice. If you are starting a new project, use .yaml by default and override to .yml only for platforms that require it.

Does `.yml` break in Kubernetes?

No. Kubernetes accepts both .yaml and .yml extensions. The kubectl apply -f file.yml command works fine with either extension. However, the Kubernetes ecosystem convention is strongly .yaml — all official documentation, examples, and tutorials use .yaml. Helm specifically requires values.yaml (not values.yml) for its default configuration file. Using .yml in a Kubernetes project works but looks inconsistent with the broader ecosystem.

Does GitHub Actions support `.yaml` files?

No — GitHub Actions only recognizes workflow files with the .yml extension in the .github/workflows/ directory. If you create a workflow file with a .yaml extension, GitHub silently ignores it. The workflow does not appear in the GitHub Actions UI, does not run on pushes or pull requests, and generates no error message. This is the one case where the file extension genuinely breaks functionality. Always use .yml for GitHub Actions workflow files.

Can I mix `.yaml` and `.yml` in the same project?

Technically yes — parsers do not care — but you should avoid it. Inconsistent extensions within a project make file searches harder (find . -name "*.yaml" misses half your files), confuse new team members, and complicate linting configurations that use extension-based globs. Standardize on one extension per project or, better yet, use .yaml by default and .yml only for platform-specific files that require it (like .github/workflows/*.yml and docker-compose.yml).

Final Thoughts

The .yaml vs .yml debate is mostly noise, but the practical implications are real.

Your CI/CD platform may not auto-detect files with the "wrong" extension. Your editor may not apply the correct schema. Your team may have inconsistent conventions that make file searches unreliable.

The pragmatic approach: use .yaml everywhere unless the target platform specifically requires .yml. This satisfies the spec recommendation, aligns with the Kubernetes ecosystem, and reserves .yml for the few platforms that genuinely need it.

And when you are working on a project with mixed extensions, paste YAML files into a formatter to verify the content, not the filename — the extension tells you nothing about whether the YAML is valid.

For more on format choice, see YAML vs JSON — When Each Makes Sense. Kubernetes operators dealing with extension conventions should read Kubernetes YAML Mistakes, and anyone debugging a file that won't parse should start with Why Your YAML Is Invalid.