yamllint

YAMLLINT(1) yamllint YAMLLINT(1)

NAME

   yamllint - Linter for YAML files

   A linter for YAML files.

   yamllint does not only check for syntax validity, but for weirdnesses like key repetition and cosmetic problems such as lines length, trailing spaces, indentation, etc.

SCREENSHOT

   [image: yamllint screenshot] [image]

   NOTE:
      The default output format is inspired by eslint, a great linting tool for Javascript.

TABLE OF CONTENTS Quickstart Running yamllint

   Basic usage:

      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 ar‐
   guments 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.

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.

Configuration

   yamllint uses a set of rules to check source files for problems.  Each rule is independent from the others, and 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):

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

   • a filename referenced by $YAMLLINT_CONFIG_FILE, if set

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

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:

      ---

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

   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.

   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.

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

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

      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.

   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

   • 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

   Use this rule to report duplicated anchors and aliases referencing undeclared anchors.

   Options

   • Set forbid-undeclared-aliases to true to avoid aliases that reference an anchor that hasn't been declared (either not declared at all, or declared later in the document).

   • Set forbid-duplicated-anchors to true to avoid duplications of a same anchor.

   • Set forbid-unused-anchors to true to avoid anchors being declared but not used anywhere in the YAML document via alias.

   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

   2. 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]

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

   Use this rule to control the use of flow mappings or number of spaces inside braces ({ and }).

   Options

   • forbid  is used to forbid the use of flow mappings which are denoted by surrounding braces ({ and }). Use true to forbid the use of flow mappings completely. Use non-empty to forbid
     the use of all flow mappings except for empty ones.

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

   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 }

   2. With braces: {forbid: non-empty}

      the following code snippet would PASS:

         object: {}

      the following code snippet would FAIL:

         object: { key1: 4, key2: 8 }

   3. 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 }

   4. 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 }

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

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

   Use this rule to control the use of flow sequences or the number of spaces inside brackets ([ and ]).

   Options

   • forbid is used to forbid the use of flow sequences which are denoted by surrounding brackets ([ and ]). Use true to forbid the use of flow sequences  completely.  Use  non-empty  to
     forbid the use of all flow sequences except for empty ones.

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

   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 ]

   2. With brackets: {forbid: non-empty}

      the following code snippet would PASS:

         object: []

      the following code snippet would FAIL:

         object: [ 1, 2, abc ]

   3. 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 ]

   4. 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 ]

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

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

   Use this rule to control the number of spaces before and after colons (:).

   Options

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

   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

   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

   Use this rule to control the number of spaces before and after commas (,).

   Options

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

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

   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 this rule to control the position and formatting of comments.

   Options

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

   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}

      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

   Use this rule to force comments to be indented like content.

   Examples

   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

   Use this rule to require or forbid the use of document end marker (...).

   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}

      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

   Use this rule to require or forbid the use of document start 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}

      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

   Use this rule to set a maximal number of allowed consecutive blank lines.

   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}

      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 this rule to prevent nodes with empty content, that implicitly result in null values.

   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:

   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}

   3. With empty-values: {forbid-in-block-sequences: true}

      the following code snippet would PASS:

         some-sequence:
           - string item

         some-sequence:
           - null

      the following code snippets would FAIL:

         some-sequence:
           -

         some-sequence:
           - string item
           -