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

  • .yamllint in the current working directory
  • $XDG_CONFIG_HOME/yamllint/config
  • ~/.config/yamllint/config

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

Default configuration

Unless told otherwise, yamllint uses its default configuration:

---

rules:
  braces:
    min-spaces-inside: 0
    max-spaces-inside: 0
  brackets:
    min-spaces-inside: 0
    max-spaces-inside: 0
  colons:
    max-spaces-before: 0
    max-spaces-after: 1
  commas:
    max-spaces-before: 0
    min-spaces-after: 1
    max-spaces-after: 1
  comments:
    level: warning
    require-starting-space: yes
    min-spaces-from-content: 2
  comments-indentation:
    level: warning
  document-end: disable
  document-start:
    level: warning
    present: yes
  empty-lines:
    max: 2
    max-start: 0
    max-end: 0
  hyphens:
    max-spaces-after: 1
  indentation:
    spaces: consistent
    indent-sequences: yes
    check-multi-line-strings: no
  key-duplicates: enable
  line-length:
    max: 80
    allow-non-breakable-words: yes
    allow-non-breakable-inline-mappings: no
  new-line-at-end-of-file: enable
  new-lines:
    type: unix
  trailing-spaces: enable

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

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.

In both cases, the script will output them (with different colors when using the standard output format), but the exit code can be different. More precisely, the script will exit will a failure code only when there is one or more error(s).