YAMLLINT(1)

📦
version 1.38.0 · 9 versions
, in ubuntu stonking

okay so you opened the manual page for YAMLLINT(1) and bestie. I got you. Pull up a chair, this is gonna be a whole moment. 💖

💖 NAME 💖

yamllint — Linter for YAML files.

It's a linter for YAML files. That's the whole vibe. 🦋

But listen, it's not just sitting there checking "does this parse, yes/no" — no ma'am. yamllint also catches the weirdnesses, like key repetition, plus all the cosmetic ✨lewks✨ problems: lines length, trailing spaces, indentation, etc. Syntax validity AND aesthetic criticism. It's giving both. Periodt. 💅

📸 SCREENSHOT 📸

[image: yamllint screenshot] [image]

Note: the default output format is inspired by eslint (https://eslint.org/), a great linting tool for Javascript. We stan a respectful homage. 👑

📖 TABLE OF CONTENTS 📖

  • Quickstart
  • Running yamllint

🏃 RUNNING YAMLLINT 🏃

💅 BASIC USAGE 💅

The bare minimum, and honestly she's enough:

yamllint file.yml other-file.yaml

You can also lint all the YAML files in a whole directory:

yamllint .

Or lint a YAML stream straight out of standard input, no files required:

echo -e 'this: is\nvalid: YAML' | yamllint -

The output will look like (colors are not displayed here, tragic, I know):

file.yml
  1:4       error    trailing spaces  (trailing-spaces)
  4:4       error    wrong indentation: expected 4 but found 3  (indentation)
  5:4       error    duplication of key "id-00042" in mapping  (key-duplicates)
  6:6       warning  comment not indented like content  (comments-indentation)
  12:6      error    too many spaces after hyphen  (hyphens)
  15:12     error    too many spaces before comma  (commas)

other-file.yaml
  1:1       warning  missing document start "---"  (document-start)
  6:81      error    line too long (87 > 80 characters)  (line-length)
  10:1      error    too many blank lines (4 > 2)  (empty-lines)
  11:4      error    too many spaces inside braces  (braces)

By default, the output of yamllint is colored when run from a terminal, and pure text in other cases. Add the -f standard arguments to force non-colored output. Use the -f colored arguments to force colored output. 🌈

Add the -f parsable arguments if you need an output format parsable by a machine (for instance for syntax highlighting in text editors). The output will then look like:

file.yml:6:2: [warning] missing starting space in comment (comments)
file.yml:57:1: [error] trailing spaces (trailing-spaces)
file.yml:60:3: [error] wrong indentation: expected 4 but found 2 (indentation)

If you have a custom linting configuration file (see how to configure yamllint), it can be passed to yamllint using the -c option:

yamllint -c ~/myconfig file.yaml
Note: if you have a .yamllint file in your working directory, it will be automatically loaded as configuration by yamllint. Surprise! It already knows. 🙈

📂 SOURCE CODE 📂

The source code of yamllint is currently hosted on GitHub at https://github.com/adrienverge/yamllint/. Releases can be found on this page https://github.com/adrienverge/yamllint/releases. Go give it a star, it deserves it. ⭐

⚙️ CONFIGURATION ⚙️

yamllint uses a set of rules to check source files for problems. Each rule is independent from the others (no drama between them, they mind their business 🧚), and each one can be enabled, disabled or tweaked. All these settings can be gathered in a configuration file.

To use a custom configuration file, use the -c option:

yamllint -c /path/to/myconfig file-to-lint.yaml

If -c is not provided, yamllint will look for a configuration file in the following locations (by order of preference):

  1. a file named .yamllint, .yamllint.yaml, or .yamllint.yml in the current working directory, or a parent directory (the search for this file is terminated at the user's home or filesystem root)
  2. a filename referenced by $YAMLLINT_CONFIG_FILE, if set
  3. a file named $XDG_CONFIG_HOME/yamllint/config or ~/.config/yamllint/config, if present

Finally if no config file is found, the default configuration is applied. Yes bestie, there is always a fallback. She's prepared. 💅

🎀 DEFAULT CONFIGURATION 🎀

Unless told otherwise, yamllint uses its default configuration:

---

yaml-files:
  - '*.yaml'
  - '*.yml'
  - '.yamllint'

rules:
  anchors: enable
  braces: enable
  brackets: enable
  colons: enable
  commas: enable
  comments:
    level: warning
  comments-indentation:
    level: warning
  document-end: disable
  document-start:
    level: warning
  empty-lines: enable
  empty-values: disable
  float-values: disable
  hyphens: enable
  indentation: enable
  key-duplicates: enable
  key-ordering: disable
  line-length: enable
  new-line-at-end-of-file: enable
  new-lines: enable
  octal-values: disable
  quoted-strings: disable
  trailing-spaces: enable
  truthy:
    level: warning

Details on rules can be found on the rules page.

There is another pre-defined configuration named relaxed. As its name suggests, it is more tolerant. She woke up and chose chill:

---

extends: default

rules:
  braces:
    level: warning
    max-spaces-inside: 1
  brackets:
    level: warning
    max-spaces-inside: 1
  colons:
    level: warning
  commas:
    level: warning
  comments: disable
  comments-indentation: disable
  document-start: disable
  empty-lines:
    level: warning
  hyphens:
    level: warning
  indentation:
    level: warning
    indent-sequences: consistent
  line-length:
    level: warning
    allow-non-breakable-inline-mappings: true
  truthy: disable

It can be chosen using:

yamllint -d relaxed file.yml

🧬 EXTENDING THE DEFAULT CONFIGURATION 🧬

When writing a custom configuration file, you don't need to redefine every rule. Just extend the default configuration (or any already-existing configuration file). Reinventing the wheel is not the move. 🛑

For instance, if you just want to disable the comments-indentation rule, your file could look like this:

# This is my first, very own configuration file for yamllint!
# It extends the default conf by adjusting some options.

extends: default

rules:
  comments-indentation: disable  # don't bother me with this rule

Similarly, if you want to set the line-length rule as a warning and be less strict on block sequences indentation:

extends: default

rules:
  # 80 chars should be enough, but don't fail if a line is longer
  line-length:
    max: 80
    level: warning

  # accept both     key:
  #                   - item
  #
  # and             key:
  #                 - item
  indentation:
    indent-sequences: whatever

🫶 CUSTOM CONFIGURATION WITHOUT A CONFIG FILE 🫶

It is possible -- although not recommended -- to pass custom configuration options to yamllint with the -d (short for --config-data) option. (Not recommended, bestie. I said what I said. 😭)

Its content can either be the name of a pre-defined conf (example: default or relaxed) or a serialized YAML object describing the configuration.

For instance:

yamllint -d "{extends: relaxed, rules: {line-length: {max: 120}}}" file.yaml

🚨 ERRORS AND WARNINGS 🚨

Problems detected by yamllint can be raised either as errors or as warnings. The CLI will output them (with different colors when using the colored output format, or auto when run from a terminal).

By default the script will exit with a return code 1 only when there is one or more error(s).

However if strict mode is enabled with the -s (or --strict) option, the return code will be:

  • 0 if no errors or warnings occur
  • 1 if one or more errors occur
  • 2 if no errors occur, but one or more warnings occur

If the script is invoked with the --no-warnings option, it won't output warning level problems, only error level ones.

📁 YAML FILES EXTENSIONS 📁

To configure what yamllint should consider as YAML files when listing directories, set yaml-files configuration option. The default is:

yaml-files:
  - '*.yaml'
  - '*.yml'
  - '.yamllint'

The same rules as for ignoring paths apply (.gitignore-style path pattern, see below).

If you need to know the exact list of files that yamllint would process, without really linting them, you can use --list-files:

yamllint --list-files .

🙅 IGNORING PATHS 🙅

It is possible to exclude specific files or directories, so that the linter doesn't process them. They can be provided either as a list of paths, or as a bulk string. Choose your fighter. ✨

You can either totally ignore files (they won't be looked at):

extends: default

ignore: |
  /this/specific/file.yaml
  all/this/directory/
  *.template.yaml

# or:

ignore:
  - /this/specific/file.yaml
  - all/this/directory/
  - '*.template.yaml'

or ignore paths only for specific rules:

extends: default

rules:
  trailing-spaces:
    ignore: |
      /this-file-has-trailing-spaces-but-it-is-OK.yaml
      /generated/*.yaml

# or:

rules:
  trailing-spaces:
    ignore:
      - /this-file-has-trailing-spaces-but-it-is-OK.yaml
      - /generated/*.yaml

Note that this .gitignore-style path pattern allows complex path exclusion/inclusion, see the pathspec README file (https://pypi.org/project/pathspec/) for more details. Here is a more complex example:

# For all rules
ignore: |
  *.dont-lint-me.yaml
  /bin/
  !/bin/*.lint-me-anyway.yaml

extends: default

rules:
  key-duplicates:
    ignore: |
      generated
      *.template.yaml
  trailing-spaces:
    ignore: |
      *.ignore-trailing-spaces.yaml
      ascii-art/*

You can also use the .gitignore file (or any list of files) through:

ignore-from-file: .gitignore

or:

ignore-from-file: [.gitignore, .yamlignore]
Note: however, this is mutually exclusive with the ignore key. Pick a lane, you can't have both. 💀
Note: files on the ignore-from-file list should use either UTF-8, UTF-16 or UTF-32. See Character Encoding for details and workarounds.

If you need to know the exact list of files that yamllint would process, without really linting them, you can use --list-files:

yamllint --list-files .

🌍 SETTING THE LOCALE 🌍

It is possible to set the locale option globally. This is passed to Python's locale.setlocale (https://docs.python.org/3/library/locale.html#locale.setlocale), so an empty string "" will use the system default locale, while e.g. "en_US.UTF-8" will use that.

Currently this only affects the key-ordering rule. The default will order by Unicode code point number, while locales will sort case and accents properly as well. Glow up behavior. 🌸

extends: default

locale: en_US.UTF-8

📜 RULES 📜

When linting a document with yamllint, a series of rules (such as line-length, trailing-spaces, etc.) are checked against.

So bestie, you can drop a config file (`<>`) to turn these rules on or off, to set their level (error or warning), and also to tweak their individual options. 💅

This page is the whole rundown of every rule and every option it has. Buckle up, it's giving encyclopedia but make it cute. 🎀

📋 List of rules

  • anchors
  • braces
  • brackets
  • colons
  • commas
  • comments
  • comments-indentation
  • document-end
  • document-start
  • empty-lines
  • empty-values
  • float-values
  • hyphens
  • indentation
  • key-duplicates
  • key-ordering
  • line-length
  • new-line-at-end-of-file
  • new-lines
  • octal-values
  • quoted-strings
  • trailing-spaces
  • truthy

⚓ anchors

This rule is your anchor police 🚨 — it reports duplicated anchors and aliases that reference an anchor nobody ever declared.

Options

  • forbid-undeclared-aliases — set it to true and you're banning aliases that point at an anchor that hasn't been declared — whether it's not declared at all, or declared later in the document. Rude, honestly.
  • forbid-duplicated-anchors — set it to true and you're banning duplicates of the same anchor. One anchor, one name, no clones. 👑
  • forbid-unused-anchors — set it to true and you're banning anchors that get declared but never used anywhere in the YAML document via an alias. No ghost anchors allowed. 💀

Default values (when enabled)

rules:
  anchors:
    forbid-undeclared-aliases: true
    forbid-duplicated-anchors: false
    forbid-unused-anchors: false

Examples

  1. With anchors: {forbid-undeclared-aliases: true}

the following code snippet would PASS:

---
- &anchor
  foo: bar
- *anchor

the following code snippet would FAIL:

---
- &anchor
  foo: bar
- *unknown

the following code snippet would FAIL:

---
- &anchor
  foo: bar
- <<: *unknown
  extra: value
  1. With anchors: {forbid-duplicated-anchors: true}

the following code snippet would PASS:

---
- &anchor1 Foo Bar
- &anchor2 [item 1, item 2]

the following code snippet would FAIL:

---
- &anchor Foo Bar
- &anchor [item 1, item 2]
  1. With anchors: {forbid-unused-anchors: true}

the following code snippet would PASS:

---
- &anchor
  foo: bar
- *anchor

the following code snippet would FAIL:

---
- &anchor
  foo: bar
- items:
  - item1
  - item2

🌸 braces

This one is all about flow mappings and how many spaces are vibing inside your braces ({ and }). Curly brace etiquette, basically. ✨

Options

  • forbid — bans flow mappings, the ones denoted by surrounding braces ({ and }). Use true to forbid flow mappings completely. Use non-empty to forbid all of them except the empty ones.
  • min-spaces-inside — the minimum number of spaces required inside braces.
  • max-spaces-inside — the maximum number of spaces allowed inside braces.
  • min-spaces-inside-empty — the minimum number of spaces required inside empty braces.
  • max-spaces-inside-empty — the maximum number of spaces allowed inside empty braces.

Default values (when enabled)

rules:
  braces:
    forbid: false
    min-spaces-inside: 0
    max-spaces-inside: 0
    min-spaces-inside-empty: -1
    max-spaces-inside-empty: -1

Examples

  1. With braces: {forbid: true}

the following code snippet would PASS:

object:
  key1: 4
  key2: 8

the following code snippet would FAIL:

object: { key1: 4, key2: 8 }
  1. With braces: {forbid: non-empty}

the following code snippet would PASS:

object: {}

the following code snippet would FAIL:

object: { key1: 4, key2: 8 }
  1. With braces: {min-spaces-inside: 0, max-spaces-inside: 0}

the following code snippet would PASS:

object: {key1: 4, key2: 8}

the following code snippet would FAIL:

object: { key1: 4, key2: 8 }
  1. With braces: {min-spaces-inside: 1, max-spaces-inside: 3}

the following code snippet would PASS:

object: { key1: 4, key2: 8 }

the following code snippet would PASS:

object: { key1: 4, key2: 8   }

the following code snippet would FAIL:

object: {    key1: 4, key2: 8   }

the following code snippet would FAIL:

object: {key1: 4, key2: 8 }
  1. With braces: {min-spaces-inside-empty: 0, max-spaces-inside-empty: 0}

the following code snippet would PASS:

object: {}

the following code snippet would FAIL:

object: { }
  1. With braces: {min-spaces-inside-empty: 1, max-spaces-inside-empty: -1}

the following code snippet would PASS:

object: {         }

the following code snippet would FAIL:

object: {}

🦋 brackets

Same energy as braces, but for flow sequences and the spaces hanging out inside brackets ([ and ]). Square squad represent. 💜

Options

  • forbid — bans flow sequences, the ones denoted by surrounding brackets ([ and ]). Use true to forbid flow sequences completely. Use non-empty to forbid all of them except the empty ones.
  • min-spaces-inside — the minimum number of spaces required inside brackets.
  • max-spaces-inside — the maximum number of spaces allowed inside brackets.
  • min-spaces-inside-empty — the minimum number of spaces required inside empty brackets.
  • max-spaces-inside-empty — the maximum number of spaces allowed inside empty brackets.

Default values (when enabled)

rules:
  brackets:
    forbid: false
    min-spaces-inside: 0
    max-spaces-inside: 0
    min-spaces-inside-empty: -1
    max-spaces-inside-empty: -1

Examples

  1. With brackets: {forbid: true}

the following code snippet would PASS:

object:
  - 1
  - 2
  - abc

the following code snippet would FAIL:

object: [ 1, 2, abc ]
  1. With brackets: {forbid: non-empty}

the following code snippet would PASS:

object: []

the following code snippet would FAIL:

object: [ 1, 2, abc ]
  1. With brackets: {min-spaces-inside: 0, max-spaces-inside: 0}

the following code snippet would PASS:

object: [1, 2, abc]

the following code snippet would FAIL:

object: [ 1, 2, abc ]
  1. With brackets: {min-spaces-inside: 1, max-spaces-inside: 3}

the following code snippet would PASS:

object: [ 1, 2, abc ]

the following code snippet would PASS:

object: [ 1, 2, abc   ]

the following code snippet would FAIL:

object: [    1, 2, abc   ]

the following code snippet would FAIL:

object: [1, 2, abc ]
  1. With brackets: {min-spaces-inside-empty: 0, max-spaces-inside-empty: 0}

the following code snippet would PASS:

object: []

the following code snippet would FAIL:

object: [ ]
  1. With brackets: {min-spaces-inside-empty: 1, max-spaces-inside-empty: -1}

the following code snippet would PASS:

object: [         ]

the following code snippet would FAIL:

object: []

🎀 colons

Spacing police for your colons (:) — both before and after. Yes bestie, whitespace counts. 🫶

Options

  • max-spaces-before — the maximum number of spaces allowed before colons (use -1 to disable this check).
  • max-spaces-after — the maximum number of spaces allowed after colons (use -1 to disable this check).

Default values (when enabled)

rules:
  colons:
    max-spaces-before: 0
    max-spaces-after: 1

Examples

  1. With colons: {max-spaces-before: 0, max-spaces-after: 1}

the following code snippet would PASS:

object:
  - a
  - b
key: value
  1. With colons: {max-spaces-before: 1}

the following code snippet would PASS:

object :
  - a
  - b

the following code snippet would FAIL:

object  :
  - a
  - b
  1. With colons: {max-spaces-after: 2}

the following code snippet would PASS:

first:  1
second: 2
third:  3

the following code snippet would FAIL:

first: 1
2nd:   2
third: 3

🍓 commas

Now it's the commas' turn (,) — we're counting spaces before and after again. Groundhog Day but with punctuation. 🙈

Options

  • max-spaces-before — the maximum number of spaces allowed before commas (use -1 to disable this check).
  • min-spaces-after — the minimum number of spaces required after commas.
  • max-spaces-after — the maximum number of spaces allowed after commas (use -1 to disable this check).

Default values (when enabled)

rules:
  commas:
    max-spaces-before: 0
    min-spaces-after: 1
    max-spaces-after: 1

Examples

  1. With commas: {max-spaces-before: 0}

the following code snippet would PASS:

strange var:
  [10, 20, 30, {x: 1, y: 2}]

the following code snippet would FAIL:

strange var:
  [10, 20 , 30, {x: 1, y: 2}]
  1. With commas: {max-spaces-before: 2}

the following code snippet would PASS:

strange var:
  [10  , 20 , 30,  {x: 1  , y: 2}]
  1. With commas: {max-spaces-before: -1}

the following code snippet would PASS:

strange var:
  [10,
   20   , 30
   ,   {x: 1, y: 2}]
  1. With commas: {min-spaces-after: 1, max-spaces-after: 1}

the following code snippet would PASS:

strange var:
  [10, 20, 30, {x: 1, y: 2}]

the following code snippet would FAIL:

strange var:
  [10, 20,30,   {x: 1,   y: 2}]
  1. With commas: {min-spaces-after: 1, max-spaces-after: 3}

the following code snippet would PASS:

strange var:
  [10, 20,  30,  {x: 1,   y: 2}]
  1. With commas: {min-spaces-after: 0, max-spaces-after: 1}

the following code snippet would PASS:

strange var:
  [10, 20,30, {x: 1, y: 2}]

💬 comments

This rule keeps an eye on where your comments live and how they're formatted. Aesthetic commentary only. 💅

Options

  • Use require-starting-space to require a space character right after the #. Set it to true to enable, false to disable.
  • Use ignore-shebangs to ignore a shebang at the beginning of the file — you know, the https://en.wikipedia.org/wiki/Shebang_(Unix) kind — when require-starting-space is set.
  • min-spaces-from-content — this is the ✨aesthetic✨ one. It defines the minimal required number of spaces between a comment and its preceding content, so your comments get to breathe instead of being glued to your code like it's codependent.

Default values (when enabled)

rules:
  comments:
    require-starting-space: true
    ignore-shebangs: true
    min-spaces-from-content: 2

Examples

  1. With comments: {require-starting-space: true}

this code snippet would PASS:

# This sentence
# is a block comment

this code snippet would PASS:

##############################
## This is some documentation

this code snippet would FAIL:

#This sentence
#is a block comment
  1. With comments: {min-spaces-from-content: 2}

this code snippet would PASS:

x = 2 ^ 127 - 1  # Mersenne prime number

this code snippet would FAIL:

x = 2 ^ 127 - 1 # Mersenne prime number

🌸 comments-indentation 🌸

Use this rule to force comments to be indented like content. Yes bestie, your comments gotta sit at the same lunch table as the code they're commenting on. 🫶

Examples

  1. With comments-indentation: {}

this code snippet would PASS:

# Fibonacci
[0, 1, 1, 2, 3, 5]

this code snippet would FAIL:

  # Fibonacci
[0, 1, 1, 2, 3, 5]

this code snippet would PASS:

list:
    - 2
    - 3
    # - 4
    - 5

this code snippet would FAIL:

list:
    - 2
    - 3
#    - 4
    - 5

this code snippet would PASS:

# This is the first object
obj1:
  - item A
  # - item B
# This is the second object
obj2: []

this code snippet would PASS:

# This sentence
# is a block comment

this code snippet would FAIL:

# This sentence
 # is a block comment

💅 document-end 💅

Use this rule to require or forbid the use of the document end marker (...). Pick a side, it's giving commitment issues otherwise. 😭

Options

  • Set present to true when the document end marker is required, or to false when it is forbidden.

Default values (when enabled)

rules:
  document-end:
    present: true

Examples

  1. With document-end: {present: true}

this code snippet would PASS:

---
this:
  is: [a, document]
...
---
- this
- is: another one
...

this code snippet would FAIL:

---
this:
  is: [a, document]
---
- this
- is: another one
...
  1. With document-end: {present: false}

this code snippet would PASS:

---
this:
  is: [a, document]
---
- this
- is: another one

this code snippet would FAIL:

---
this:
  is: [a, document]
...
---
- this
- is: another one

⭐ document-start ⭐

Use this rule to require or forbid the use of the document start marker (---). Same energy as the last one, different marker. 🎀

Options

  • Set present to true when the document start marker is required, or to false when it is forbidden.

Default values (when enabled)

rules:
  document-start:
    present: true

Examples

  1. With document-start: {present: true}

this code snippet would PASS:

---
this:
  is: [a, document]
---
- this
- is: another one

this code snippet would FAIL:

this:
  is: [a, document]
---
- this
- is: another one
  1. With document-start: {present: false}

this code snippet would PASS:

this:
  is: [a, document]
...

this code snippet would FAIL:

---
this:
  is: [a, document]
...

🦋 empty-lines 🦋

Use this rule to set a maximal number of allowed consecutive blank lines. The vibes need some breathing room but not a whole void, yk? 💀

Options

  • max defines the maximal number of empty lines allowed in the document.
  • max-start defines the maximal number of empty lines allowed at the beginning of the file. This option takes precedence over max.
  • max-end defines the maximal number of empty lines allowed at the end of the file. This option takes precedence over max.

Default values (when enabled)

rules:
  empty-lines:
    max: 2
    max-start: 0
    max-end: 0

Examples

  1. With empty-lines: {max: 1}

this code snippet would PASS:

- foo:
    - 1
    - 2

- bar: [3, 4]

this code snippet would FAIL:

- foo:
    - 1
    - 2


- bar: [3, 4]

🍓 empty-values 🍓

Use this rule to prevent nodes with empty content, that implicitly result in null values. It's the "no thoughts, head empty" rule, but for YAML. 🙈

Options

  • Use forbid-in-block-mappings to prevent empty values in block mappings.
  • Use forbid-in-flow-mappings to prevent empty values in flow mappings.
  • Use forbid-in-block-sequences to prevent empty values in block sequences.

Default values (when enabled)

rules:
  empty-values:
    forbid-in-block-mappings: true
    forbid-in-flow-mappings: true
    forbid-in-block-sequences: true

Examples

  1. With empty-values: {forbid-in-block-mappings: true}

the following code snippets would PASS:

some-mapping:
  sub-element: correctly indented

explicitly-null: null

the following code snippets would FAIL:

some-mapping:
sub-element: incorrectly indented

implicitly-null:
  1. With empty-values: {forbid-in-flow-mappings: true}

this code snippet would PASS:

{prop: null}
{a: 1, b: 2, c: 3}

the following code snippets would FAIL:

{prop: }

{a: 1, b:, c: 3}
  1. With empty-values: {forbid-in-block-sequences: true}

this code snippet would PASS:

some-sequence:
  - string item

some-sequence:
  - null

the following code snippets would FAIL:

some-sequence:
  -

some-sequence:
  - string item
  -

🧚 float-values 🧚

Use this rule to limit the permitted values for floating-point numbers. YAML permits three classes of float expressions: approximation to real numbers, positive and negative infinity and "not a number". Yeah, YAML said "let's allow chaos" and this rule said "not on my watch". 👑

Options

  • Use require-numeral-before-decimal to require floats to start with a numeral (ex 0.0 instead of .0).
  • Use forbid-scientific-notation to forbid scientific notation.
  • Use forbid-nan to forbid NaN (not a number) values.
  • Use forbid-inf to forbid infinite values.

Default values (when enabled)

rules:
  float-values:
    forbid-inf: false
    forbid-nan: false
    forbid-scientific-notation: false
    require-numeral-before-decimal: false

Examples

  1. With float-values: {require-numeral-before-decimal: true}

the following code snippets would PASS:

anemometer:
  angle: 0.0

the following code snippets would FAIL:

anemometer:
  angle: .0
  1. With float-values: {forbid-scientific-notation: true}

the following code snippets would PASS:

anemometer:
  angle: 0.00001

the following code snippets would FAIL:

anemometer:
  angle: 10e-6
  1. With float-values: {forbid-nan: true}

the following code snippets would FAIL:

anemometer:
  angle: .NaN
  1. With float-values: {forbid-inf: true}

the following code snippets would FAIL:

anemometer:
  angle: .inf

💖 hyphens 💖

Use this rule to control the number of spaces after hyphens (-). Little dash, big personality. 🌈

Options

  • max-spaces-after defines the maximal number of spaces allowed after hyphens.

Default values (when enabled)

rules:
  hyphens:
    max-spaces-after: 1

Examples

  1. With hyphens: {max-spaces-after: 1}

this code snippet would PASS:

- first list:
    - a
    - b
- - 1
  - 2
  - 3

this code snippet would FAIL:

-  first list:
     - a
     - b

this code snippet would FAIL:

- - 1
  -  2
  - 3
  1. With hyphens: {max-spaces-after: 3}

this code snippet would PASS:

-   key
-  key2
- key42

this code snippet would FAIL:

-    key
-   key2
-  key42

✨ indentation ✨

Use this rule to control the indentation. Lowkey the main character of all the rules, no cap. 👑

Options

  • spaces defines the indentation width, in spaces. Set either to an integer (e.g. 2 or 4, representing the number of spaces in an indentation level) or to consistent to allow any number, as long as it remains the same within the file.
  • indent-sequences defines whether block sequences should be indented or not (when in a mapping, this indentation is not mandatory -- some people perceive the - as part of the indentation). Possible values: true, false, whatever and consistent. consistent requires either all block sequences to be indented, or none to be. whatever means either indenting or not indenting individual block sequences is OK.
  • check-multi-line-strings defines whether to lint indentation in multi-line strings. Set to true to enable, false to disable.

Default values (when enabled)

rules:
  indentation:
    spaces: consistent
    indent-sequences: true
    check-multi-line-strings: false

Examples

  1. With indentation: {spaces: 1}

this code snippet would PASS:

history:
 - name: Unix
   date: 1969
 - name: Linux
   date: 1991
nest:
 recurse:
  - haystack:
     needle
  1. With indentation: {spaces: 4}

this code snippet would PASS:

history:
    - name: Unix
      date: 1969
    - name: Linux
      date: 1991
nest:
    recurse:
        - haystack:
              needle

this code snippet would FAIL:

  1. With indentation: {spaces: consistent} ✨

this snippet PASSES 🫶:

history:
   - name: Unix
     date: 1969
   - name: Linux
     date: 1991
nest:
   recurse:
      - haystack:
           needle

and this snippet FAILS 💀:

some:
  Russian:
      dolls
  1. With indentation: {spaces: 2, indent-sequences: false} 🌸

PASS ✅:

list:
- flying
- spaghetti
- monster

FAIL 🙈:

list:
  - flying
  - spaghetti
  - monster
  1. With indentation: {spaces: 2, indent-sequences: whatever} 🦋

PASS ✨:

list:
- flying:
  - spaghetti
  - monster
- not flying:
    - spaghetti
    - sauce
  1. With indentation: {spaces: 2, indent-sequences: consistent} 💜

PASS 💖:

- flying:
  - spaghetti
  - monster
- not flying:
  - spaghetti
  - sauce

FAIL 💀:

- flying:
    - spaghetti
    - monster
- not flying:
  - spaghetti
  - sauce
  1. With indentation: {spaces: 4, check-multi-line-strings: true} 🎀

PASS 🌈:

Blaise Pascal:
    Je vous écris une longue lettre parce que
    je n'ai pas le temps d'en écrire une courte.

PASS again 👑:

Blaise Pascal: Je vous écris une longue lettre parce que
               je n'ai pas le temps d'en écrire une courte.

FAIL 😭:

Blaise Pascal: Je vous écris une longue lettre parce que
  je n'ai pas le temps d'en écrire une courte.

FAIL 💀:

C code:
    void main() {
        printf("foo");
    }

PASS 🫶:

C code:
    void main() {
    printf("bar");
    }

key-duplicates 🔑

This rule stops you from putting the same key twice inside a mapping. No duplicate keys, bestie, it's giving chaos energy 🙅‍♀️

Options

  • forbid-duplicated-merge-keys — turn this on to forbid using multiple merge keys <<.

Default values (when enabled)

rules:
  key-duplicates:
    forbid-duplicated-merge-keys: false

Examples

  1. With key-duplicates: {} ✨

PASS 💖:

- key 1: v
  key 2: val
  key 3: value
- {a: 1, b: 2, c: 3}

FAIL 💀:

- key 1: v
  key 2: val
  key 1: value

FAIL 🙈:

- {a: 1, b: 2, b: 3}

FAIL 😭:

duplicated key: 1
"duplicated key": 2

other duplication: 1
? >-
    other
    duplication
: 2
  1. With key-duplicates: {forbid-duplicated-merge-keys: true} 🌸

PASS ✅:

anchor_one: &anchor_one
  one: one
anchor_two: &anchor_two
  two: two
anchor_reference:
  <<: [*anchor_one, *anchor_two]

FAIL 💀:

anchor_one: &anchor_one
  one: one
anchor_two: &anchor_two
  two: two
anchor_reference:
  <<: *anchor_one
  <<: *anchor_two

key-ordering 🔤

This rule makes your keys alphabetical in mappings, periodt. By default the sorting order uses the Unicode code point number, which means the ordering is case-sensitive and not accent-friendly (peep the examples below, they're wild 👀). You can flip that by setting the global locale option — that's how you get case and accents sorted properly. Slay 🌍

Options

  • ignored-keys — a list of PCRE regexes. Any key that matches one of them gets skipped while the order check is happening.

Default values (when enabled)

rules:
  key-ordering:
    ignored-keys: []

Examples

  1. With key-ordering: {} ✨

PASS 👑:

- key 1: v
  key 2: val
  key 3: value
- {a: 1, b: 2, c: 3}
- T-shirt: 1
  T-shirts: 2
  t-shirt: 3
  t-shirts: 4
- hair: true
  hais: true
  haïr: true
  haïssable: true

FAIL 💀:

- key 2: v
  key 1: val

FAIL 🙈:

- {b: 1, a: 2}

FAIL 😭:

- T-shirt: 1
  t-shirt: 2
  T-shirts: 3
  t-shirts: 4

FAIL 💀:

- haïr: true
  hais: true
  1. With global option locale: "en_US.UTF-8" and rule key-ordering: {} 🌈

so like, opposite of before — this one now PASSES 💖:

- t-shirt: 1
  T-shirt: 2
  t-shirts: 3
  T-shirts: 4
- hair: true
  haïr: true
  hais: true
  haïssable: true
  1. With rule key-ordering: {ignored-keys: ["name"]} 🎀

PASS ✨:

- a:
  b:
  name: ignored
  first-name: ignored
  c:
  d:

line-length 📏

This rule puts a limit on how long your lines can be. Short king lines only 💅

Options

  • max — the maximal (and yes, inclusive) length of lines.
  • allow-non-breakable-words — lets non breakable words (the ones with no spaces inside) spill over the limit. Super handy for long URLs, fr fr. Use true to allow, false to forbid.
  • allow-non-breakable-inline-mappings — implies allow-non-breakable-words and extends it so non-breakable words inside inline mappings are allowed too.

Default values (when enabled)

rules:
  line-length:
    max: 80
    allow-non-breakable-words: true
    allow-non-breakable-inline-mappings: false

Examples

  1. With line-length: {max: 70} ✨

PASS 💖:

long sentence:
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
  eiusmod tempor incididunt ut labore et dolore magna aliqua.

FAIL 💀:

long sentence:
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
  tempor incididunt ut labore et dolore magna aliqua.
  1. With line-length: {max: 60, allow-non-breakable-words: true} 🌸

PASS 🫶:

this:
  is:
    - a:
        http://localhost/very/very/very/very/very/very/very/very/long/url

# this comment is too long,
# but hard to split:
# http://localhost/another/very/very/very/very/very/very/very/very/long/url

FAIL 😭:

- this line is waaaaaaaaaaaaaay too long but could be easily split...

and this one FAILS too 💀:

- foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
  1. With line-length: {max: 60, allow-non-breakable-words: true, allow-non-breakable-inline-mappings: true} 🦋

PASS 👑:

- foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
  1. With line-length: {max: 60, allow-non-breakable-words: false} 🙈

FAIL 💀:

this:
  is:
    - a:
        http://localhost/very/very/very/very/very/very/very/very/long/url

new-line-at-end-of-file 🌙

This rule says: your file needs a new line character (\n) at the end. That's it, that's the rule.

The POSIX standard requires the last line to end with a new line character: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_206. All UNIX tools expect a new line at the end of files, and most text editors roll with this convention too. It's just the vibe 🫶

new-lines 🚂

This rule forces the type of new line characters you're using.

Options

  • Set type to unix to enforce UNIX-typed new line characters (\n), set type to dos to enforce DOS-typed new line characters (\r\n), or set type to platform to infer the type from whatever system is running yamllint (\n on POSIX / UNIX / Linux / Mac OS systems, or \r\n on DOS / Windows systems).

Default values (when enabled)

rules:
  new-lines:
    type: unix

octal-values 🐙

This rule keeps values from being octal numbers. In YAML, numbers that start with 0 get read as octal, and honestly? Not always what you wanted. For instance 010 is the city code of Beijing and it should not become 8. Not me getting my city codes mangled 😭

Options

  • Use forbid-implicit-octal to prevent numbers starting with 0.
  • Use forbid-explicit-octal to prevent numbers starting with 0o.

Default values (when enabled)

rules:
  octal-values:
    forbid-implicit-octal: true
    forbid-explicit-octal: true

Examples

  1. With octal-values: {forbid-implicit-octal: true} ✨

these snippets PASS 💖:

user:
  city-code: '010'

these snippets PASS 🌸:

user:
  city-code: 010,021

these snippets FAIL 💀:

user:
  city-code: 010
  1. With octal-values: {forbid-explicit-octal: true} 🦋

these snippets PASS 👑:

user:
  city-code: '0o10'

these snippets FAIL 😭:

user:
  city-code: 0o10

quoted-strings 🎀

This rule can forbid any string values that aren't quoted, or flip it around and prevent quoted strings that didn't even need the quotes. You can also enforce which type of quote gets used. So many options, so much power 💅

Options

  • quote-type — defines the allowed quotes: single, double, consistent or any (default).
  • required — defines whether using quotes in string values is required (true, default) or not (false), or only allowed when it's really needed (only-when-needed).
  • extra-required — a list of PCRE regexes that force string values to be quoted if they match any regex. Heads up bestie, this option can only be used with required: false and required: only-when-needed.
  • extra-allowed — a list of PCRE regexes for quoted string values you want to allow even when required: only-when-needed is turned on. like, "yes bestie, quotes here are fine, leave her alone" 💅
  • allow-quoted-quotes — lets you (true) use the disallowed kind of quote for strings that have the allowed quote living inside them. Default is false. 🎀
  • check-keys — decides whether these rules get applied to the keys in your mappings. by default the quoted-strings rules only touch the values. flip this to true and the rules come for your keys too 👀
Note: Multi-line strings (the ones using | or >) will not be checked. nope, not those. 🙈

Default values (when enabled) — this is what you get out the box:

rules:
  quoted-strings:
    quote-type: any
    required: true
    extra-required: []
    extra-allowed: []
    allow-quoted-quotes: false
    check-keys: false

Examples ✨

  1. With quoted-strings: {quote-type: any, required: true}

this snippet PASSES:

foo: "bar"
bar: 'foo'
number: 123
boolean: true

this snippet FAILS:

foo: bar
  1. With quoted-strings: {quote-type: single, required: only-when-needed}

this snippet PASSES:

foo: bar
bar: foo
not_number: '123'
not_boolean: 'true'
not_comment: '# comment'
not_list: '[1, 2, 3]'
not_map: '{a: 1, b: 2}'

this snippet FAILS:

foo: 'bar'
  1. With quoted-strings: {required: false, extra-required: [^http://, ^ftp://]}

this snippet PASSES:

- localhost
- "localhost"
- "http://localhost"
- "ftp://localhost"

this snippet FAILS:

- http://localhost
- ftp://localhost
  1. With quoted-strings: {required: only-when-needed, extra-allowed: [^http://, ^ftp://], extra-required: [QUOTED]}

this snippet PASSES:

- localhost
- "http://localhost"
- "ftp://localhost"
- "this is a string that needs to be QUOTED"

this snippet FAILS:

- "localhost"
- this is a string that needs to be QUOTED
  1. With quoted-strings: {quote-type: double, allow-quoted-quotes: false}

this snippet PASSES:

foo: "bar\"baz"

this snippet FAILS:

foo: 'bar"baz'
  1. With quoted-strings: {quote-type: double, allow-quoted-quotes: true}

this snippet PASSES:

foo: 'bar"baz'
  1. With quoted-strings: {quote-type: consistent}

this snippet PASSES:

foo: 'bar'
baz: 'quux'

this snippet FAILS:

foo: 'bar'
baz: "quux"
  1. With quoted-strings: {required: only-when-needed, check-keys: true, extra-required: ["[:]"]}

this snippet FAILS:

foo:bar: baz

this snippet PASSES:

"foo:bar": baz

✂️ trailing-spaces ✂️

Use this rule to forbid trailing spaces at the end of lines. those sneaky little ghosts at the end of your line? not on this linter's watch. 👻

Examples

  1. With trailing-spaces: {}

this snippet PASSES:

this document doesn't contain
any trailing
spaces

this snippet FAILS:

this document contains
trailing spaces
on lines 1 and 3

🫣 truthy 🫣

Use this rule to forbid non-explicitly typed truthy values that aren't on the allowed list (which is true and false by default). so like, YES or off — cute but no. 🙅‍♀️

this is genuinely useful, because YAML parsers love to surprise you: [yes, FALSE, Off] can get transformed into [true, false, false], and {y: 1, yes: 2, on: 3, true: 4, True: 5} can become {y: 1, true: 5}. the betrayal. 😭

depending on which YAML specification version your document is using, the list of truthy values changes. In YAML 1.2, only capitalized / uppercased combinations of true and false count as truthy, whereas in YAML 1.1 combinations of yes, no, on and off do too. To make the YAML spec version explicit in a document, you can drop a %YAML 1.2 directive in there (example below 👇).

Options

  • allowed-values — the list of truthy values that get ignored during linting. The default is ['true', 'false'], but you can change it to any list containing: 'TRUE', 'True', 'true', 'FALSE', 'False', 'false', 'YES', 'Yes', 'yes', 'NO', 'No', 'no', 'ON', 'On', 'on', 'OFF', 'Off', 'off'. pick your fighters 🥊
  • check-keys — disables verification for keys in mappings. By default, the truthy rule applies to both keys and values. Set this option to false to stop that from happening.

Default values (when enabled)

rules:
  truthy:
    allowed-values: ['true', 'false']
    check-keys: true

Examples

  1. With truthy: {}

this snippet PASSES:

boolean: true

object: {"True": 1, 1: "True"}

"yes":  1
"on":   2
"True": 3

explicit:
  string1: !!str True
  string2: !!str yes
  string3: !!str off
  encoded: !!binary |
             True
             OFF
             pad==  # this decodes as 'N»8Qii'
  boolean1: !!bool true
  boolean2: !!bool "false"
  boolean3: !!bool FALSE
  boolean4: !!bool True
  boolean5: !!bool off
  boolean6: !!bool NO

this snippet FAILS:

object: {True: 1, 1: True}

this snippet FAILS:

%YAML 1.1
---
yes:  1
on:   2
True: 3

this snippet PASSES:

%YAML 1.2
---
yes:  1
on:   2
true: 3
  1. With truthy: {allowed-values: ["yes", "no"]}

this snippet PASSES:

- yes
- no
- "true"
- 'false'
- foo
- bar

this snippet FAILS:

- true
- false
- on
- off
  1. With truthy: {check-keys: false}

this snippet PASSES:

yes:  1
on:   2
true: 3

this snippet FAILS:

yes:  Yes
on:   On
true: True

🚫 Disable with comments 🚫

🌸 Disabling checks for a specific line 🌸

To stop yamllint from reporting problems on one specific line, add a directive comment (# yamllint disable-line ...) on that line, or on the line right above it. like this, bestie:

# The following mapping contains the same key twice,
# but I know what I'm doing:
- key: value 1
  key: value 2  # yamllint disable-line rule:key-duplicates

- This line is waaaaaaaaaay too long but yamllint will not report anything about it.  # yamllint disable-line rule:line-length
- This line will be checked by yamllint.

or like this, with the comment chilling on the line above:

# The following mapping contains the same key twice,
# but I know what I'm doing:
- key: value 1
  # yamllint disable-line rule:key-duplicates
  key: value 2

# yamllint disable-line rule:line-length
- This line is waaaaaaaaaay too long but yamllint will not report anything about it.
- This line will be checked by yamllint.

It is possible to disable all the rules for a specific line, although we genuinely don't recommend it:

# yamllint disable-line
-  {    all : rules ,are disabled   for this line}
You can't make yamllint ignore invalid YAML syntax on a line (the kind that generates a syntax error) — like when you're templating a YAML file with Jinja. In some cases you can work around it by putting the templating syntax in a YAML comment. see Putting template flow control in comments.

If you need to disable multiple rules, you're allowed to chain them like this: # yamllint disable-line rule:hyphens rule:commas rule:indentation. 🔗

💜 Disabling checks for all (or part of) the file 💜

To stop yamllint from reporting problems for the whole file, or for a block of lines inside the file, use the # yamllint disable ... and # yamllint enable ... directive comments. for instance:

# yamllint disable rule:colons
- Lorem       : ipsum
  dolor       : sit amet,
  consectetur : adipiscing elit
# yamllint enable rule:colons

- rest of the document...

It is possible to disable all the rules, although again, we don't recommend it:

# yamllint disable
- Lorem       :
        ipsum:
          dolor : [   sit,amet]
-         consectetur : adipiscing elit
# yamllint enable

If you need to disable multiple rules, chaining works here too: # yamllint disable rule:hyphens rule:commas rule:indentation.

👑 Disabling all checks for a file 👑

To stop yamllint from reporting problems for one specific file, add the directive comment # yamllint disable-file as the first line of the file. for instance:

# yamllint disable-file
# The following mapping contains the same key twice, but I know what I'm doing:
- key: value 1
  key: value 2

- This line is waaaaaaaaaay too long but yamllint will not report anything about it.

or:

# yamllint disable-file
# This file is not valid YAML because it is a Jinja template
{% if extra_info %}
key1: value1
{% endif %}
key2: value2

🧚 Putting template flow control in comments 🧚

As an alternative for templating, you can wrap the template statements in comments to make it a valid YAML file. As long as the templating language doesn't use the same comment symbol, it should be a valid template and valid YAML (before and after template processing). 🌈

Example of a Jinja2 code that cannot be parsed as YAML because it contains the invalid tokens {% and %}:

# This file IS NOT valid YAML and will produce syntax errors
{% if extra_info %}
key1: value1
{% endif %}
key2: value2

But it can be fixed using YAML comments:

# This file IS valid YAML because the Jinja is in a YAML comment
# {% if extra_info %}
key1: value1
# {% endif %}
key2: value2

🛠️ Development 🛠️

yamllint ships both a script and a Python module. The Python module is the one you use when you want to write your own linting tools. build your own era, honestly. 💅

Basic example of running the linter from Python:

import yamllint.config
import yamllint.linter

yaml_config = yamllint.config.YamlLintConfig("extends: default")
for p in yamllint.linter.run(open("example.yaml", "r"), yaml_config):
    print(p.desc, p.line, p.rule)

class yamllint.linter.LintProblem(line, column, desc='<no description>', rule=None)

Represents a linting problem found by yamllint. one little problem, packaged up 🎁

  • column — Column on which the problem was found (starting at 1)
  • desc — a human-readable lil description of whatever went wrong 🥺
  • line — the line where the problem was found (counting starts at 1, bestie, not 0 💅)
  • rule — the identifier of the rule that caught it 👮‍♀️

🫶 yamllint.linter.run(input, conf, filepath=None)

Lints a YAML source. That's it, that's the job ✨

Returns a generator of LintProblem objects — so like, it hands you problems one at a time instead of dumping them all at once, very chill of it 🦋

Parameters

  • input — buffer, string or stream to read from
  • conf — yamllint configuration object

🧚 Integration with text editors

Okay so basically every text editor out here supports syntax checking and highlighting, like, to visually report syntax errors and warnings to you. And yamllint can absolutely be the one doing that YAML syntax-checking 💅 — you just need a lil bit of config depending on which editor is your main character 🌸

💻 Vim

Assuming you've got the ALE plugin installed (https://github.com/dense-analysis/ale), yamllint is supported by default. No cap. It's automatically enabled the second you start editing YAML files 👑

But if you're instead a syntastic girlie (https://github.com/vim-syntastic/syntastic), just add this to your .vimrc:

let g:syntastic_yaml_checkers = ['yamllint']

🌙 Neovim

Assuming the neomake plugin is installed (https://github.com/neomake/neomake), yamllint is supported by default. Again — automatically enabled when editing YAML files. The way that it just works 😭💖

🐃 Emacs

If you are a flycheck user (https://github.com/flycheck/flycheck), you can use the flycheck-yamllint integration (https://github.com/krzysztof-magosa/flycheck-yamllint). Slay 🎀

🩵 Visual Studio Code

https://marketplace.visualstudio.com/items?itemName=fnando.linter

That's it, that's the whole section, go click it bestie ✨

🧠 IntelliJ

https://plugins.jetbrains.com/plugin/15349-yamllint

Same vibe. Plugin link, do your thing 💜

🌈 Other text editors

Help wanted! 🥺

Is your fave text editor not listed here? Help us improve by adding a section (by opening a pull-request or issue on GitHub). We're literally begging, in a cute way 🙈

🔧 Integration with other software

🪝 Integration with pre-commit

You can integrate yamllint into the pre-commit tool (https://pre-commit.com/) 💅 Here's an example, to add in your .pre-commit-config.yaml:

---
# Update the rev variable with the release version that you want, from the yamllint repo
# You can pass your custom .yamllint with args attribute.
repos:
  - repo: https://github.com/adrienverge/yamllint.git
    rev: v1.29.0
    hooks:
      - id: yamllint
        args: [--strict, -c=/path/to/.yamllint]

🐙 Integration with GitHub Actions

yamllint auto-detects when it's running inside of GitHub Actions (https://github.com/features/actions) and automatically uses the suited output format to decorate your code with linting errors ✨ (ngl that's kind of iconic of it). You can also force the GitHub Actions output with yamllint --format github.

A minimal example workflow using GitHub Actions:

---
on: push  # yamllint disable-line rule:truthy

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install yamllint
        run: pip install yamllint

      - name: Lint YAML files
        run: yamllint .

🦊 Integration with GitLab

You can use the following GitLab CI/CD stage to run yamllint and get the results as a Code quality (Code Climate) report (https://docs.gitlab.com/ee/ci/testing/code_quality.html) 💅

---
lint:
  stage: lint
  script:
    - pip install yamllint
    - mkdir reports
    - >
      yamllint -f parsable . | tee >(awk '
      BEGIN {FS = ":"; ORS="\n"; first=1}
      {
          gsub(/^[ \t]+|[ \t]+$|"/, "", $4);
          match($4, /^\[(warning|error)\](.*)\((.*)\)$/, a);
          sev = (a[1] == "error" ? "major" : "minor");
          if (first) {
              first=0;
              printf("[");
          } else {
              printf(",");
          }
          printf("{\"location\":{\"path\":\"%s\",\"lines\":{\"begin\":%s,"\
                 "\"end\":%s}},\"severity\":\"%s\",\"check_name\":\"%s\","\
                 "\"categories\":[\"Style\"],\"type\":\"issue\","\
                 "\"description\":\"%s\"}", $1, $2, $3, sev, a[3], a[2]);
      }
      END { if (!first) printf("]\n"); }' > reports/codequality.json)
  artifacts:
    when: always
    paths:
      - reports
    expire_in: 1 week
    reports:
      codequality: reports/codequality.json

Like… that awk script is a lot but it eats, fr fr 🔥

🏹 Integration with Arcanist

You can configure yamllint to run on arc lint 💅 Here's an example .arclint file that makes use of this configuration:

{
  "linters": {
    "yamllint": {
      "type": "script-and-regex",
      "script-and-regex.script": "yamllint",
      "script-and-regex.regex": "/^(?P<line>\\d+):(?P<offset>\\d+) +(?P<severity>warning|error) +(?P<message>.*) +\\((?P<name>.*)\\)$/m",
      "include": "(\\.(yml|yaml)$)"
    }
  }
}

🔤 Character Encoding

Okay so this part matters 🫶 When yamllint reads a file (whether it's a configuration file or a file to lint), yamllint will try to automatically detect that file's character encoding. For the automatic detection to work properly, files must follow these two rules (see this section of the YAML specification for details, https://yaml.org/spec/1.2.2/#52-character-encodings):

  • The file must be encoded in UTF-8, UTF-16 or UTF-32.
  • The file must begin with either a byte order mark or an ASCII character.

🪄 Override character encoding

Previous versions of yamllint did not try to autodetect the character encoding of files. Instead, previous versions of yamllint assumed that files used the current locale's character encoding. Which meant older versions of yamllint would sometimes correctly decode files that didn't follow those two rules 😭 (lucky them).

For the sake of backwards compatibility, the current version of yamllint lets you disable automatic character encoding detection by setting the YAMLLINT_FILE_ENCODING environment variable. If you set YAMLLINT_FILE_ENCODING to the the name of one of Python's standard character encodings (https://docs.python.org/3/library/codecs.html#standard-encodings), then yamllint will use that character encoding instead of trying to autodetect the character encoding ✨

🚨 Bestie listen to me: the YAMLLINT_FILE_ENCODING environment variable should only be used as a stopgap solution. If you need to use YAMLLINT_FILE_ENCODING, then you should really update your YAML files so that their character encoding can automatically be detected, or else you may run into compatibility problems. Future versions of yamllint may remove support for the YAMLLINT_FILE_ENCODING environment variable, and other YAML processors may misinterpret your YAML files. That's not a vibe, that's a warning 💀

👑 Author

Adrien Vergé

2022, Adrien Vergé

and that's the whole page, we're done, we ate and left no crumbs 🍓💖 huge thanks to Adrien Vergé for authoring and holding the copyright (2022, Adrien Vergé), and this whole thing ships as version 1.38.0 dated Mar 30, 2026 — YAMLLINT(1), periodt 💅🎀✨

📦 where this page comes from