A YAML file stores information in a format that both humans and computers can read

A YAML file is a plain-text document that holds structured data — like settings, configuration options, or lists of items — written in a way that looks closer to English than to code. YAML stands for "YAML Ain't Markup Language," which is a recursive joke programmers use, but what matters is this: when you open a YAML file in any text editor, you can actually understand what you're looking at without special training.

The file extension is .yaml or .yml (both work the same way). You'll encounter YAML files when you're setting up software, configuring servers, writing automation scripts, or working with tools like Docker, Kubernetes, Ansible, or GitHub Actions. The format became popular because it's simpler than older formats like XML or JSON, which use more brackets and punctuation.

Key Takeaways

  • YAML files use indentation (spaces, not tabs) to show how data relates to each other, making them readable without special symbols.
  • The most common use is storing configuration settings that programs read when they start up or run a task.
  • A single space or indentation error will break a YAML file, so precision matters even though the format looks simple.
  • YAML files are plain text, so you can edit them in Notepad, VS Code, or any text editor — no special software needed.

How YAML organizes information using indentation

YAML uses indentation — the spaces at the start of each line — to show which pieces of data belong together. This is different from JSON, which uses curly braces and brackets, or XML, which uses angle brackets. In YAML, if something is indented further to the right, it belongs to the thing above it.

Here's a concrete example. If you were storing information about a server, a YAML file might look like this:

server:   name: web-server-01   port: 8080   location: us-east-1 database:   host: db.example.com   port: 5432

The indentation tells you that "name," "port," and "location" all describe the server, while "host" and "port" describe the database. No brackets needed. The colon after each label separates the label from its value. This structure is called a key-value pair — "name" is the key, and "web-server-01" is the value.

Common places you'll see YAML files in real projects

Docker uses YAML files called docker-compose.yml to describe how multiple containers should run together. Kubernetes uses YAML to define how applications should be deployed and managed. GitHub Actions, which automates tasks when you push code to a repository, stores its instructions in YAML files inside a .github/workflows folder.

Ansible, a tool for automating server setup and configuration, reads YAML files called playbooks that describe what tasks to run on which machines. Many configuration management tools and infrastructure-as-code platforms rely on YAML because it's easier for teams to read and review than other formats. If you're working with any modern DevOps tool, you're probably working with YAML.

Why indentation matters more than it looks

YAML is strict about indentation in a way that can frustrate beginners. You must use spaces, not tabs, and the number of spaces must be consistent. If you indent something two spaces in one place and four spaces in another, the file breaks. Many text editors have settings to convert tabs to spaces automatically, which helps avoid this problem.

A single misaligned line can cause the entire file to fail. When a program reads a broken YAML file, it usually returns an error message that points to a line number but doesn't always explain that the problem is indentation. This is why many developers use a YAML validator — a tool that checks your file before you try to use it. VS Code, a popular code editor, has extensions that highlight indentation problems as you type.

Lists and nested structures in YAML

YAML can store lists using a dash and a space. If you wanted to list multiple servers, you'd write:

servers:   - name: web-01     port: 8080   - name: web-02     port: 8081

The dash indicates each item in the list. Everything indented under each dash belongs to that item. You can nest lists inside other structures, creating complex hierarchies. This flexibility is one reason YAML became the standard for configuration files — it can represent almost any structure a program needs to read.

YAML versus JSON and XML

JSON uses curly braces and square brackets, making it more compact but harder to scan visually. XML uses opening and closing tags like HTML, which is verbose and repetitive. YAML strips away most of this syntax, relying on indentation instead. The trade-off is that YAML is more sensitive to formatting mistakes, while JSON and XML are more forgiving because they use explicit markers.

For configuration files that humans write and edit regularly, YAML wins. For data that gets passed between systems automatically, JSON is often preferred because it's stricter and harder to misformat accidentally. Many modern tools support all three formats, but YAML has become the default for infrastructure and DevOps work.

How to edit and validate YAML files

You can edit a YAML file in any text editor — Notepad, VS Code, Sublime Text, or even the default editor on your operating system. The key is to save it with the correct extension (.yaml or .yml) so programs know what format to expect. Many editors have plugins or built-in support for YAML that will highlight syntax errors and show you indentation levels.

Before you use a YAML file in a real project, run it through a validator. Online YAML validators exist at sites like yamllint.com or jsonschema.net, and most development tools include validation built in. If you're using VS Code, install the "YAML" extension by Red Hat, which validates as you type and catches indentation problems immediately. This saves hours of debugging later.

Frequently Asked Questions

Can I use tabs instead of spaces in YAML?

No. YAML requires spaces for indentation. If you use tabs, the file will fail to parse. Most text editors have a setting to convert tabs to spaces automatically — turn this on when working with YAML files.

What happens if my YAML file has an error?

The program trying to read it will return a parse error, usually with a line number. The error message doesn't always clearly explain that indentation is wrong, so check spacing first. Use a YAML validator to pinpoint the exact problem.

Is YAML only used for configuration?

Mostly, but not always. YAML is used for configuration files, infrastructure definitions, CI/CD pipelines, and data storage. It's designed to be human-readable, so any situation where people need to write or edit structured data by hand is a good fit for YAML.

Can YAML files contain comments?

Yes. Anything after a hash symbol (#) on a line is treated as a comment and ignored by the program. Comments are useful for explaining what each section does, especially in complex configuration files.

Do I need special software to open a YAML file?

No. YAML files are plain text, so any text editor works. However, using an editor with YAML support (like VS Code with the YAML extension) helps catch errors before you use the file.