Quickstart¶

Installing yamllint¶

sudo dnf install yamllint

On Debian 8+ / Ubuntu 16.04+:

sudo apt-get install yamllint

On Mac OS 10.11+:

brew install yamllint

Alternatively using pip, the Python package manager:

pip install --user yamllint

If you prefer installing from source, you can run, from the source directory:

python setup.py sdist
pip install --user dist/yamllint-*.tar.gz

Running yamllint¶

yamllint file.yml other-file.yaml

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

yamllint .

Or lint a YAML stream from standard input:

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

The output will look like (colors are not displayed here):

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:

Configuration¶

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):

Finally if no config file is found, the default configuration is applied.

Default configuration¶

---
rules:
  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: enable
  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: enable
  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:

---
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¶

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¶

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¶

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:

Ignoring paths¶

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 paths only for specific rules:

extends: default
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 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/*

Rules¶

A configuration file can be used to enable or disable these rules, to set their level (error or warning), but also to tweak their options.

This page describes the rules and their options.

List of rules¶

braces¶

• min-spaces-inside defines the minimal number of spaces required inside braces.
• max-spaces-inside defines the maximal number of spaces allowed inside braces.
• min-spaces-inside-empty defines the minimal number of spaces required inside empty braces.
• max-spaces-inside-empty defines the maximal number of spaces allowed inside empty braces.

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 }

2.

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 }

3.

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: { }

4.

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¶

• min-spaces-inside defines the minimal number of spaces required inside brackets.
• max-spaces-inside defines the maximal number of spaces allowed inside brackets.
• min-spaces-inside-empty defines the minimal number of spaces required inside empty brackets.
• max-spaces-inside-empty defines the maximal number of spaces allowed inside empty brackets.

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 ]

2.

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 ]

3.

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: [ ]

4.

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¶

• max-spaces-before defines the maximal number of spaces allowed before colons (use -1 to disable).
• max-spaces-after defines the maximal number of spaces allowed after colons (use -1 to disable).

1.

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

the following code snippet would PASS:

object:
  - a
  - b
key: value

2.

With colons: {max-spaces-before: 1}

the following code snippet would PASS:

object :
  - a
  - b

the following code snippet would FAIL:

object  :
  - a
  - b

3.

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¶

• max-spaces-before defines the maximal number of spaces allowed before commas (use -1 to disable).
• min-spaces-after defines the minimal number of spaces required after commas.
• max-spaces-after defines the maximal number of spaces allowed after commas (use -1 to disable).

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}]

2.

With commas: {max-spaces-before: 2}

the following code snippet would PASS:

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

3.

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

the following code snippet would PASS:

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

4.

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}]

5.

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}]

6.

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¶

• Use require-starting-space to require a space character right after the #. Set to true to enable, false to disable.
• Use ignore-shebangs to ignore a shebang at the beginning of the file when require-starting-space is set.
• min-spaces-from-content is used to visually separate inline comments from content. It defines the minimal required number of spaces between a comment and its preceding content.

1.

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

the following code snippet would PASS:

# This sentence
# is a block comment

the following code snippet would PASS:

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

the following code snippet would FAIL:

#This sentence
#is a block comment

2.

With comments: {min-spaces-from-content: 2}

the following code snippet would PASS:

x = 2 ^ 127 - 1  # Mersenne prime number

the following code snippet would FAIL:

x = 2 ^ 127 - 1 # Mersenne prime number

comments-indentation¶

1.

With comments-indentation: {}

the following code snippet would PASS:

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

the following code snippet would FAIL:

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

the following code snippet would PASS:

list:
    - 2
    - 3
    # - 4
    - 5

the following code snippet would FAIL:

list:
    - 2
    - 3
#    - 4
    - 5

the following code snippet would PASS:

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

the following code snippet would PASS:

# This sentence
# is a block comment

the following code snippet would FAIL:

# This sentence
 # is a block comment

document-end¶

•

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

1.

With document-end: {present: true}

the following code snippet would PASS:

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

the following code snippet would FAIL:

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

2.

With document-end: {present: false}

the following code snippet would PASS:

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

the following code snippet would FAIL:

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

document-start¶

•

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

1.

With document-start: {present: true}

the following code snippet would PASS:

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

the following code snippet would FAIL:

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

2.

With document-start: {present: false}

the following code snippet would PASS:

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

the following code snippet would FAIL:

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

empty-lines¶

• 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.

1.

With empty-lines: {max: 1}

the following code snippet would PASS:

- foo:
    - 1
    - 2
- bar: [3, 4]

the following code snippet would FAIL:

- foo:
    - 1
    - 2
- bar: [3, 4]

empty-values¶

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

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:

2.

With empty-values: {forbid-in-flow-mappings: true}

the following code snippet would PASS:

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

the following code snippets would FAIL:

{prop: }

{a: 1, b:, c: 3}

hyphens¶

•

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

1.

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

the following code snippet would PASS:

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

the following code snippet would FAIL:

-  first list:
     - a
     - b

the following code snippet would FAIL:

- - 1
  -  2
  - 3

2.

With hyphens: {max-spaces-after: 3}

the following code snippet would PASS:

-   key
-  key2
- key42

the following code snippet would FAIL:

-    key
-   key2
-  key42

indentation¶

• 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.

1.

With indentation: {spaces: 1}

the following code snippet would PASS:

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

2.

With indentation: {spaces: 4}

the following code snippet would PASS:

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

the following code snippet would FAIL:

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

3.

With indentation: {spaces: consistent}

the following code snippet would PASS:

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

the following code snippet would FAIL:

some:
  Russian:
      dolls

4.

With indentation: {spaces: 2, indent-sequences: false}

the following code snippet would PASS:

list:
- flying
- spaghetti
- monster

the following code snippet would FAIL:

list:
  - flying
  - spaghetti
  - monster

5.

With indentation: {spaces: 2, indent-sequences: whatever}

the following code snippet would PASS:

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

6.

With indentation: {spaces: 2, indent-sequences: consistent}

the following code snippet would PASS:

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

the following code snippet would FAIL:

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

7.

With indentation: {spaces: 4, check-multi-line-strings: true}

the following code snippet would PASS:

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

the following code snippet would PASS:

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

the following code snippet would FAIL:

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

the following code snippet would FAIL:

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

the following code snippet would PASS:

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

key-duplicates¶

1.

With key-duplicates: {}

the following code snippet would PASS:

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

the following code snippet would FAIL:

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

the following code snippet would FAIL:

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

the following code snippet would FAIL:

duplicated key: 1
"duplicated key": 2
other duplication: 1
? >-
    other
    duplication
: 2

key-ordering¶

1.

With key-ordering: {}

the following code snippet would 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

the following code snippet would FAIL:

- key 2: v
  key 1: val

the following code snippet would FAIL:

- {b: 1, a: 2}

the following code snippet would FAIL:

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

the following code snippet would FAIL:

- haïr: true
  hais: true

line-length¶

Note: with Python 2, the line-length rule may not work properly with unicode characters because of the way strings are represented in bytes. We recommend running yamllint with Python 3. Options.INDENT 0.0

• max defines the maximal (inclusive) length of lines.
• allow-non-breakable-words is used to allow non breakable words (without spaces inside) to overflow the limit. This is useful for long URLs, for instance. Use true to allow, false to forbid.
• allow-non-breakable-inline-mappings implies allow-non-breakable-words and extends it to also allow non-breakable words in inline mappings.

1.

With line-length: {max: 70}

the following code snippet would PASS:

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

the following code snippet would FAIL:

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

2.

With line-length: {max: 60, allow-non-breakable-words: true}

the following code snippet would 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

the following code snippet would FAIL:

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

and the following code snippet would also FAIL:

- foobar: http://localhost/very/very/very/very/very/very/very/very/long/url

3.

With line-length: {max: 60, allow-non-breakable-words: true, allow-non-breakable-inline-mappings: true}

the following code snippet would PASS:

- foobar: http://localhost/very/very/very/very/very/very/very/very/long/url

4.

With line-length: {max: 60, allow-non-breakable-words: false}

the following code snippet would FAIL:

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

new-line-at-end-of-file¶

The POSIX standard requires the last line to end with a new line character. All UNIX tools expect a new line at the end of files. Most text editors use this convention too.

new-lines¶

•

Set type to unix to use UNIX-typed new line characters (\n), or dos to use DOS-typed new line characters (\r\n).

octal-values¶

1.

With octal-values: {forbid-implicit-octal: true}

the following code snippets would PASS:

user:
  city-code: '010'

the following code snippets would PASS:

user:
  city-code: 010,021

the following code snippets would FAIL:

user:
  city-code: 010

2.

With octal-values: {forbid-explicit-octal: true}

the following code snippets would PASS:

user:
  city-code: '0o10'

the following code snippets would FAIL:

user:
  city-code: 0o10

quoted-strings¶

Note: Multi-line strings (with | or >) will not be checked. Examples.INDENT 0.0

1.

With quoted-strings: {quote-type: any}

the following code snippet would PASS:

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

the following code snippet would FAIL:

foo: bar

trailing-spaces¶

1.

With trailing-spaces: {}

the following code snippet would PASS:

this document doesn't contain
any trailing
spaces

the following code snippet would FAIL:

this document contains     
trailing spaces
on lines 1 and 3         

truthy¶

This can be useful to prevent surprises from YAML parsers transforming [yes, FALSE, Off] into [true, false, false] or {y: 1, yes: 2, on: 3, true: 4, True: 5} into {y: 1, true: 5}. Examples.INDENT 0.0

1.

With truthy: {}

the following code snippet would PASS:

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

the following code snippet would FAIL:

object: {True: 1, 1: True}

the following code snippet would FAIL:

yes:  1
on:   2
True: 3

Disable with comments¶

Disabling checks for a specific line¶

# 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:

# 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, although not recommend, to disabled all rules for a specific line:

# yamllint disable-line
-  {    all : rules ,are disabled   for this line}

If you need to disable multiple rules, it is allowed to chain rules like this: # yamllint disable-line rule:hyphens rule:commas rule:indentation.

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

# yamllint disable rule:colons
- Lorem       : ipsum
  dolor       : sit amet,
  consectetur : adipiscing elit
# yamllint enable rule:colons
- rest of the document...

It is possible, although not recommend, to disabled all rules:

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

If you need to disable multiple rules, it is allowed to chain rules like this: # yamllint disable rule:hyphens rule:commas rule:indentation.

Development¶

Integration with text editors¶

Vim¶

If you instead use the syntastic plugin, add this to your .vimrc:

let g:syntastic_yaml_checkers = ['yamllint']

Neovim¶

Emacs¶

Other text editors¶

Your favorite text editor is not listed here? Help us improve by adding a section (by opening a pull-request or issue on GitHub).

Integration with other software¶

Integration with pre-commit¶

---
# Update the sha variable with the release version that you want, from the yamllint repo
- repo: https://github.com/adrienverge/yamllint.git
  sha: v1.8.1
  hooks:
    - id: yamllint