1YAMLLINT(1) yamllint YAMLLINT(1)
2
6 yamllint - Linter for YAML files
7 A linter for YAML files.
9 yamllint does not only check for syntax validity, but for weirdnesses
11 like key repetition and cosmetic problems such as lines length, trail‐
12 ing spaces, indentation, etc.
13
15 [image: yamllint screenshot] [image]
16 NOTE:
18 The default output format is inspired by eslint, a great linting
19 tool for Javascript.
20
22 Quickstart
23 Installing yamllint
24 On Fedora / CentOS (note: EPEL is required on CentOS):
25 sudo dnf install yamllint
27 On Debian 8+ / Ubuntu 16.04+:
29 sudo apt-get install yamllint
31 On Mac OS 10.11+:
33 brew install yamllint
35 On FreeBSD:
37 pkg install py36-yamllint
39 On OpenBSD:
41 doas pkg_add py3-yamllint
43 Alternatively using pip, the Python package manager:
45 pip install --user yamllint
47 If you prefer installing from source, you can run, from the source di‐
49 rectory:
50 python setup.py sdist
52 pip install --user dist/yamllint-*.tar.gz
53 Running yamllint
55 Basic usage:
56 yamllint file.yml other-file.yaml
58 You can also lint all YAML files in a whole directory:
60 yamllint .
62 Or lint a YAML stream from standard input:
64 echo -e 'this: is\nvalid: YAML' | yamllint -
66 The output will look like (colors are not displayed here):
68 file.yml
70 1:4 error trailing spaces (trailing-spaces)
71 4:4 error wrong indentation: expected 4 but found 3 (indentation)
72 5:4 error duplication of key "id-00042" in mapping (key-duplicates)
73 6:6 warning comment not indented like content (comments-indentation)
74 12:6 error too many spaces after hyphen (hyphens)
75 15:12 error too many spaces before comma (commas)
76 other-file.yaml
78 1:1 warning missing document start "---" (document-start)
79 6:81 error line too long (87 > 80 characters) (line-length)
80 10:1 error too many blank lines (4 > 2) (empty-lines)
81 11:4 error too many spaces inside braces (braces)
82 By default, the output of yamllint is colored when run from a terminal,
84 and pure text in other cases. Add the -f standard arguments to force
85 non-colored output. Use the -f colored arguments to force colored out‐
86 put.
87 Add the -f parsable arguments if you need an output format parsable by
89 a machine (for instance for syntax highlighting in text editors). The
90 output will then look like:
91 file.yml:6:2: [warning] missing starting space in comment (comments)
93 file.yml:57:1: [error] trailing spaces (trailing-spaces)
94 file.yml:60:3: [error] wrong indentation: expected 4 but found 2 (indentation)
95 If you have a custom linting configuration file (see how to configure
97 yamllint), it can be passed to yamllint using the -c option:
98 yamllint -c ~/myconfig file.yaml
100 NOTE:
102 If you have a .yamllint file in your working directory, it will be
103 automatically loaded as configuration by yamllint.
104 Configuration
106 yamllint uses a set of rules to check source files for problems. Each
107 rule is independent from the others, and can be enabled, disabled or
108 tweaked. All these settings can be gathered in a configuration file.
109 To use a custom configuration file, use the -c option:
111 yamllint -c /path/to/myconfig file-to-lint.yaml
113 If -c is not provided, yamllint will look for a configuration file in
115 the following locations (by order of preference):
116 • a file named .yamllint, .yamllint.yaml, or .yamllint.yml in the cur‐
118 rent working directory
119 • a filename referenced by $YAMLLINT_CONFIG_FILE, if set
121 • a file named $XDG_CONFIG_HOME/yamllint/config or ~/.config/yam‐
123 llint/config, if present
124 Finally if no config file is found, the default configuration is ap‐
126 plied.
127 Default configuration
129 Unless told otherwise, yamllint uses its default configuration:
130 ---
132 yaml-files:
134 - '*.yaml'
135 - '*.yml'
136 - '.yamllint'
137 rules:
139 braces: enable
140 brackets: enable
141 colons: enable
142 commas: enable
143 comments:
144 level: warning
145 comments-indentation:
146 level: warning
147 document-end: disable
148 document-start:
149 level: warning
150 empty-lines: enable
151 empty-values: disable
152 float-values: disable
153 hyphens: enable
154 indentation: enable
155 key-duplicates: enable
156 key-ordering: disable
157 line-length: enable
158 new-line-at-end-of-file: enable
159 new-lines: enable
160 octal-values: disable
161 quoted-strings: disable
162 trailing-spaces: enable
163 truthy:
164 level: warning
165 Details on rules can be found on the rules page.
168 There is another pre-defined configuration named relaxed. As its name
170 suggests, it is more tolerant:
171 ---
173 extends: default
175 rules:
177 braces:
178 level: warning
179 max-spaces-inside: 1
180 brackets:
181 level: warning
182 max-spaces-inside: 1
183 colons:
184 level: warning
185 commas:
186 level: warning
187 comments: disable
188 comments-indentation: disable
189 document-start: disable
190 empty-lines:
191 level: warning
192 hyphens:
193 level: warning
194 indentation:
195 level: warning
196 indent-sequences: consistent
197 line-length:
198 level: warning
199 allow-non-breakable-inline-mappings: true
200 truthy: disable
201 It can be chosen using:
204 yamllint -d relaxed file.yml
206 Extending the default configuration
208 When writing a custom configuration file, you don't need to redefine
209 every rule. Just extend the default configuration (or any already-ex‐
210 isting configuration file).
211 For instance, if you just want to disable the comments-indentation
213 rule, your file could look like this:
214 # This is my first, very own configuration file for yamllint!
216 # It extends the default conf by adjusting some options.
217 extends: default
219 rules:
221 comments-indentation: disable # don't bother me with this rule
222 Similarly, if you want to set the line-length rule as a warning and be
224 less strict on block sequences indentation:
225 extends: default
227 rules:
229 # 80 chars should be enough, but don't fail if a line is longer
230 line-length:
231 max: 80
232 level: warning
233 # accept both key:
235 # - item
236 #
237 # and key:
238 # - item
239 indentation:
240 indent-sequences: whatever
241 Custom configuration without a config file
243 It is possible -- although not recommended -- to pass custom configura‐
244 tion options to yamllint with the -d (short for --config-data) option.
245 Its content can either be the name of a pre-defined conf (example: de‐
247 fault or relaxed) or a serialized YAML object describing the configura‐
248 tion.
249 For instance:
251 yamllint -d "{extends: relaxed, rules: {line-length: {max: 120}}}" file.yaml
253 Errors and warnings
255 Problems detected by yamllint can be raised either as errors or as
256 warnings. The CLI will output them (with different colors when using
257 the colored output format, or auto when run from a terminal).
258 By default the script will exit with a return code 1 only when there is
260 one or more error(s).
261 However if strict mode is enabled with the -s (or --strict) option, the
263 return code will be:
264 • 0 if no errors or warnings occur
266 • 1 if one or more errors occur
268 • 2 if no errors occur, but one or more warnings occur
270 If the script is invoked with the --no-warnings option, it won't output
272 warning level problems, only error level ones.
273 YAML files extensions
275 To configure what yamllint should consider as YAML files when listing
276 directories, set yaml-files configuration option. The default is:
277 yaml-files:
279 - '*.yaml'
280 - '*.yml'
281 - '.yamllint'
282 The same rules as for ignoring paths apply (.gitignore-style path pat‐
284 tern, see below).
285 If you need to know the exact list of files that yamllint would
287 process, without really linting them, you can use --list-files:
288 yamllint --list-files .
290 Ignoring paths
292 It is possible to exclude specific files or directories, so that the
293 linter doesn't process them. They can be provided either as a list of
294 paths, or as a bulk string.
295 You can either totally ignore files (they won't be looked at):
297 extends: default
299 ignore: |
301 /this/specific/file.yaml
302 all/this/directory/
303 *.template.yaml
304 # or:
306 ignore:
308 - /this/specific/file.yaml
309 - all/this/directory/
310 - '*.template.yaml'
311 or ignore paths only for specific rules:
313 extends: default
315 rules:
317 trailing-spaces:
318 ignore: |
319 /this-file-has-trailing-spaces-but-it-is-OK.yaml
320 /generated/*.yaml
321 # or:
323 rules:
325 trailing-spaces:
326 ignore:
327 - /this-file-has-trailing-spaces-but-it-is-OK.yaml
328 - /generated/*.yaml
329 Note that this .gitignore-style path pattern allows complex path exclu‐
331 sion/inclusion, see the pathspec README file for more details. Here is
332 a more complex example:
333 # For all rules
335 ignore: |
336 *.dont-lint-me.yaml
337 /bin/
338 !/bin/*.lint-me-anyway.yaml
339 extends: default
341 rules:
343 key-duplicates:
344 ignore: |
345 generated
346 *.template.yaml
347 trailing-spaces:
348 ignore: |
349 *.ignore-trailing-spaces.yaml
350 ascii-art/*
351 You can also use the .gitignore file (or any list of files) through:
353 ignore-from-file: .gitignore
355 or:
357 ignore-from-file: [.gitignore, .yamlignore]
359 NOTE:
361 However, this is mutually exclusive with the ignore key.
362 If you need to know the exact list of files that yamllint would
364 process, without really linting them, you can use --list-files:
365 yamllint --list-files .
367 Setting the locale
369 It is possible to set the locale option globally. This is passed to
370 Python's locale.setlocale, so an empty string "" will use the system
371 default locale, while e.g. "en_US.UTF-8" will use that.
372 Currently this only affects the key-ordering rule. The default will or‐
374 der by Unicode code point number, while locales will sort case and ac‐
375 cents properly as well.
376 extends: default
378 locale: en_US.UTF-8
380 Rules
382 When linting a document with yamllint, a series of rules (such as
383 line-length, trailing-spaces, etc.) are checked against.
384 A configuration file can be used to enable or disable these rules, to
386 set their level (error or warning), but also to tweak their options.
387 This page describes the rules and their options.
389 List of rules
391 • braces
392 • brackets
394 • colons
396 • commas
398 • comments
400 • comments-indentation
402 • document-end
404 • document-start
406 • empty-lines
408 • empty-values
410 • float-values
412 • hyphens
414 • indentation
416 • key-duplicates
418 • key-ordering
420 • line-length
422 • new-line-at-end-of-file
424 • new-lines
426 • octal-values
428 • quoted-strings
430 • trailing-spaces
432 • truthy
434 braces
436 Use this rule to control the use of flow mappings or number of spaces
437 inside braces ({ and }).
438 Options
440 • forbid is used to forbid the use of flow mappings which are denoted
442 by surrounding braces ({ and }). Use true to forbid the use of flow
443 mappings completely. Use non-empty to forbid the use of all flow map‐
444 pings except for empty ones.
445 • min-spaces-inside defines the minimal number of spaces required in‐
447 side braces.
448 • max-spaces-inside defines the maximal number of spaces allowed inside
450 braces.
451 • min-spaces-inside-empty defines the minimal number of spaces required
453 inside empty braces.
454 • max-spaces-inside-empty defines the maximal number of spaces allowed
456 inside empty braces.
457 Default values (when enabled)
459 rules:
461 braces:
462 forbid: false
463 min-spaces-inside: 0
464 max-spaces-inside: 0
465 min-spaces-inside-empty: -1
466 max-spaces-inside-empty: -1
467 Examples
469 1. With braces: {forbid: true}
471 the following code snippet would PASS:
473 object:
475 key1: 4
476 key2: 8
477 the following code snippet would FAIL:
479 object: { key1: 4, key2: 8 }
481 2. With braces: {forbid: non-empty}
483 the following code snippet would PASS:
485 object: {}
487 the following code snippet would FAIL:
489 object: { key1: 4, key2: 8 }
491 3. With braces: {min-spaces-inside: 0, max-spaces-inside: 0}
493 the following code snippet would PASS:
495 object: {key1: 4, key2: 8}
497 the following code snippet would FAIL:
499 object: { key1: 4, key2: 8 }
501 4. With braces: {min-spaces-inside: 1, max-spaces-inside: 3}
503 the following code snippet would PASS:
505 object: { key1: 4, key2: 8 }
507 the following code snippet would PASS:
509 object: { key1: 4, key2: 8 }
511 the following code snippet would FAIL:
513 object: { key1: 4, key2: 8 }
515 the following code snippet would FAIL:
517 object: {key1: 4, key2: 8 }
519 5. With braces: {min-spaces-inside-empty: 0, max-spaces-inside-empty:
521 0}
522 the following code snippet would PASS:
524 object: {}
526 the following code snippet would FAIL:
528 object: { }
530 6. With braces: {min-spaces-inside-empty: 1, max-spaces-inside-empty:
532 -1}
533 the following code snippet would PASS:
535 object: { }
537 the following code snippet would FAIL:
539 object: {}
541 brackets
543 Use this rule to control the use of flow sequences or the number of
544 spaces inside brackets ([ and ]).
545 Options
547 • forbid is used to forbid the use of flow sequences which are denoted
549 by surrounding brackets ([ and ]). Use true to forbid the use of flow
550 sequences completely. Use non-empty to forbid the use of all flow se‐
551 quences except for empty ones.
552 • min-spaces-inside defines the minimal number of spaces required in‐
554 side brackets.
555 • max-spaces-inside defines the maximal number of spaces allowed inside
557 brackets.
558 • min-spaces-inside-empty defines the minimal number of spaces required
560 inside empty brackets.
561 • max-spaces-inside-empty defines the maximal number of spaces allowed
563 inside empty brackets.
564 Default values (when enabled)
566 rules:
568 brackets:
569 forbid: false
570 min-spaces-inside: 0
571 max-spaces-inside: 0
572 min-spaces-inside-empty: -1
573 max-spaces-inside-empty: -1
574 Examples
576 1. With brackets: {forbid: true}
578 the following code snippet would PASS:
580 object:
582 - 1
583 - 2
584 - abc
585 the following code snippet would FAIL:
587 object: [ 1, 2, abc ]
589 2. With brackets: {forbid: non-empty}
591 the following code snippet would PASS:
593 object: []
595 the following code snippet would FAIL:
597 object: [ 1, 2, abc ]
599 3. With brackets: {min-spaces-inside: 0, max-spaces-inside: 0}
601 the following code snippet would PASS:
603 object: [1, 2, abc]
605 the following code snippet would FAIL:
607 object: [ 1, 2, abc ]
609 4. With brackets: {min-spaces-inside: 1, max-spaces-inside: 3}
611 the following code snippet would PASS:
613 object: [ 1, 2, abc ]
615 the following code snippet would PASS:
617 object: [ 1, 2, abc ]
619 the following code snippet would FAIL:
621 object: [ 1, 2, abc ]
623 the following code snippet would FAIL:
625 object: [1, 2, abc ]
627 5. With brackets: {min-spaces-inside-empty: 0, max-spaces-inside-empty:
629 0}
630 the following code snippet would PASS:
632 object: []
634 the following code snippet would FAIL:
636 object: [ ]
638 6. With brackets: {min-spaces-inside-empty: 1, max-spaces-inside-empty:
640 -1}
641 the following code snippet would PASS:
643 object: [ ]
645 the following code snippet would FAIL:
647 object: []
649 colons
651 Use this rule to control the number of spaces before and after colons
652 (:).
653 Options
655 • max-spaces-before defines the maximal number of spaces allowed before
657 colons (use -1 to disable).
658 • max-spaces-after defines the maximal number of spaces allowed after
660 colons (use -1 to disable).
661 Default values (when enabled)
663 rules:
665 colons:
666 max-spaces-before: 0
667 max-spaces-after: 1
668 Examples
670 1. With colons: {max-spaces-before: 0, max-spaces-after: 1}
672 the following code snippet would PASS:
674 object:
676 - a
677 - b
678 key: value
679 2. With colons: {max-spaces-before: 1}
681 the following code snippet would PASS:
683 object :
685 - a
686 - b
687 the following code snippet would FAIL:
689 object :
691 - a
692 - b
693 3. With colons: {max-spaces-after: 2}
695 the following code snippet would PASS:
697 first: 1
699 second: 2
700 third: 3
701 the following code snippet would FAIL:
703 first: 1
705 2nd: 2
706 third: 3
707 commas
709 Use this rule to control the number of spaces before and after commas
710 (,).
711 Options
713 • max-spaces-before defines the maximal number of spaces allowed before
715 commas (use -1 to disable).
716 • min-spaces-after defines the minimal number of spaces required after
718 commas.
719 • max-spaces-after defines the maximal number of spaces allowed after
721 commas (use -1 to disable).
722 Default values (when enabled)
724 rules:
726 commas:
727 max-spaces-before: 0
728 min-spaces-after: 1
729 max-spaces-after: 1
730 Examples
732 1. With commas: {max-spaces-before: 0}
734 the following code snippet would PASS:
736 strange var:
738 [10, 20, 30, {x: 1, y: 2}]
739 the following code snippet would FAIL:
741 strange var:
743 [10, 20 , 30, {x: 1, y: 2}]
744 2. With commas: {max-spaces-before: 2}
746 the following code snippet would PASS:
748 strange var:
750 [10 , 20 , 30, {x: 1 , y: 2}]
751 3. With commas: {max-spaces-before: -1}
753 the following code snippet would PASS:
755 strange var:
757 [10,
758 20 , 30
759 , {x: 1, y: 2}]
760 4. With commas: {min-spaces-after: 1, max-spaces-after: 1}
762 the following code snippet would PASS:
764 strange var:
766 [10, 20, 30, {x: 1, y: 2}]
767 the following code snippet would FAIL:
769 strange var:
771 [10, 20,30, {x: 1, y: 2}]
772 5. With commas: {min-spaces-after: 1, max-spaces-after: 3}
774 the following code snippet would PASS:
776 strange var:
778 [10, 20, 30, {x: 1, y: 2}]
779 6. With commas: {min-spaces-after: 0, max-spaces-after: 1}
781 the following code snippet would PASS:
783 strange var:
785 [10, 20,30, {x: 1, y: 2}]
786 comments
788 Use this rule to control the position and formatting of comments.
789 Options
791 • Use require-starting-space to require a space character right after
793 the #. Set to true to enable, false to disable.
794 • Use ignore-shebangs to ignore a shebang at the beginning of the file
796 when require-starting-space is set.
797 • min-spaces-from-content is used to visually separate inline comments
799 from content. It defines the minimal required number of spaces be‐
800 tween a comment and its preceding content.
801 Default values (when enabled)
803 rules:
805 comments:
806 require-starting-space: true
807 ignore-shebangs: true
808 min-spaces-from-content: 2
809 Examples
811 1. With comments: {require-starting-space: true}
813 the following code snippet would PASS:
815 # This sentence
817 # is a block comment
818 the following code snippet would PASS:
820 ##############################
822 ## This is some documentation
823 the following code snippet would FAIL:
825 #This sentence
827 #is a block comment
828 2. With comments: {min-spaces-from-content: 2}
830 the following code snippet would PASS:
832 x = 2 ^ 127 - 1 # Mersenne prime number
834 the following code snippet would FAIL:
836 x = 2 ^ 127 - 1 # Mersenne prime number
838 comments-indentation
840 Use this rule to force comments to be indented like content.
841 Examples
843 1. With comments-indentation: {}
845 the following code snippet would PASS:
847 # Fibonacci
849 [0, 1, 1, 2, 3, 5]
850 the following code snippet would FAIL:
852 # Fibonacci
854 [0, 1, 1, 2, 3, 5]
855 the following code snippet would PASS:
857 list:
859 - 2
860 - 3
861 # - 4
862 - 5
863 the following code snippet would FAIL:
865 list:
867 - 2
868 - 3
869 # - 4
870 - 5
871 the following code snippet would PASS:
873 # This is the first object
875 obj1:
876 - item A
877 # - item B
878 # This is the second object
879 obj2: []
880 the following code snippet would PASS:
882 # This sentence
884 # is a block comment
885 the following code snippet would FAIL:
887 # This sentence
889 # is a block comment
890 document-end
892 Use this rule to require or forbid the use of document end marker
893 (...).
894 Options
896 • Set present to true when the document end marker is required, or to
898 false when it is forbidden.
899 Default values (when enabled)
901 rules:
903 document-end:
904 present: true
905 Examples
907 1. With document-end: {present: true}
909 the following code snippet would PASS:
911 ---
913 this:
914 is: [a, document]
915 ...
916 ---
917 - this
918 - is: another one
919 ...
920 the following code snippet would FAIL:
922 ---
924 this:
925 is: [a, document]
926 ---
927 - this
928 - is: another one
929 ...
930 2. With document-end: {present: false}
932 the following code snippet would PASS:
934 ---
936 this:
937 is: [a, document]
938 ---
939 - this
940 - is: another one
941 the following code snippet would FAIL:
943 ---
945 this:
946 is: [a, document]
947 ...
948 ---
949 - this
950 - is: another one
951 document-start
953 Use this rule to require or forbid the use of document start marker
954 (---).
955 Options
957 • Set present to true when the document start marker is required, or to
959 false when it is forbidden.
960 Default values (when enabled)
962 rules:
964 document-start:
965 present: true
966 Examples
968 1. With document-start: {present: true}
970 the following code snippet would PASS:
972 ---
974 this:
975 is: [a, document]
976 ---
977 - this
978 - is: another one
979 the following code snippet would FAIL:
981 this:
983 is: [a, document]
984 ---
985 - this
986 - is: another one
987 2. With document-start: {present: false}
989 the following code snippet would PASS:
991 this:
993 is: [a, document]
994 ...
995 the following code snippet would FAIL:
997 ---
999 this:
1000 is: [a, document]
1001 ...
1002 empty-lines
1004 Use this rule to set a maximal number of allowed consecutive blank
1005 lines.
1006 Options
1008 • max defines the maximal number of empty lines allowed in the docu‐
1010 ment.
1011 • max-start defines the maximal number of empty lines allowed at the
1013 beginning of the file. This option takes precedence over max.
1014 • max-end defines the maximal number of empty lines allowed at the end
1016 of the file. This option takes precedence over max.
1017 Default values (when enabled)
1019 rules:
1021 empty-lines:
1022 max: 2
1023 max-start: 0
1024 max-end: 0
1025 Examples
1027 1. With empty-lines: {max: 1}
1029 the following code snippet would PASS:
1031 - foo:
1033 - 1
1034 - 2
1035 - bar: [3, 4]
1037 the following code snippet would FAIL:
1039 - foo:
1041 - 1
1042 - 2
1043 - bar: [3, 4]
1046 empty-values
1048 Use this rule to prevent nodes with empty content, that implicitly re‐
1049 sult in null values.
1050 Options
1052 • Use forbid-in-block-mappings to prevent empty values in block map‐
1054 pings.
1055 • Use forbid-in-flow-mappings to prevent empty values in flow mappings.
1057 Default values (when enabled)
1059 rules:
1061 empty-values:
1062 forbid-in-block-mappings: true
1063 forbid-in-flow-mappings: true
1064 Examples
1066 1. With empty-values: {forbid-in-block-mappings: true}
1068 the following code snippets would PASS:
1070 some-mapping:
1072 sub-element: correctly indented
1073 explicitly-null: null
1075 the following code snippets would FAIL:
1077 some-mapping:
1079 sub-element: incorrectly indented
1080 implicitly-null:
1082 2. With empty-values: {forbid-in-flow-mappings: true}
1084 the following code snippet would PASS:
1086 {prop: null}
1088 {a: 1, b: 2, c: 3}
1089 the following code snippets would FAIL:
1091 {prop: }
1093 {a: 1, b:, c: 3}
1095 float-values
1097 Use this rule to limit the permitted values for floating-point numbers.
1098 YAML permits three classes of float expressions: approximation to real
1099 numbers, positive and negative infinity and "not a number".
1100 Options
1102 • Use require-numeral-before-decimal to require floats to start with a
1104 numeral (ex 0.0 instead of .0).
1105 • Use forbid-scientific-notation to forbid scientific notation.
1107 • Use forbid-nan to forbid NaN (not a number) values.
1109 • Use forbid-inf to forbid infinite values.
1111 Default values (when enabled)
1113 rules:
1115 float-values:
1116 forbid-inf: false
1117 forbid-nan: false
1118 forbid-scientific-notation: false
1119 require-numeral-before-decimal: false
1120 Examples
1122 1. With float-values: {require-numeral-before-decimal: true}
1124 the following code snippets would PASS:
1126 anemometer:
1128 angle: 0.0
1129 the following code snippets would FAIL:
1131 anemometer:
1133 angle: .0
1134 2. With float-values: {forbid-scientific-notation: true}
1136 the following code snippets would PASS:
1138 anemometer:
1140 angle: 0.00001
1141 the following code snippets would FAIL:
1143 anemometer:
1145 angle: 10e-6
1146 3. With float-values: {forbid-nan: true}
1148 the following code snippets would FAIL:
1150 anemometer:
1152 angle: .NaN
1153 1. With float-values: {forbid-inf: true}
1155 the following code snippets would FAIL:
1156 anemometer:
1158 angle: .inf
1159 hyphens
1161 Use this rule to control the number of spaces after hyphens (-).
1162 Options
1164 • max-spaces-after defines the maximal number of spaces allowed after
1166 hyphens.
1167 Default values (when enabled)
1169 rules:
1171 hyphens:
1172 max-spaces-after: 1
1173 Examples
1175 1. With hyphens: {max-spaces-after: 1}
1177 the following code snippet would PASS:
1179 - first list:
1181 - a
1182 - b
1183 - - 1
1184 - 2
1185 - 3
1186 the following code snippet would FAIL:
1188 - first list:
1190 - a
1191 - b
1192 the following code snippet would FAIL:
1194 - - 1
1196 - 2
1197 - 3
1198 2. With hyphens: {max-spaces-after: 3}
1200 the following code snippet would PASS:
1202 - key
1204 - key2
1205 - key42
1206 the following code snippet would FAIL:
1208 - key
1210 - key2
1211 - key42
1212 indentation
1214 Use this rule to control the indentation.
1215 Options
1217 • spaces defines the indentation width, in spaces. Set either to an in‐
1219 teger (e.g. 2 or 4, representing the number of spaces in an indenta‐
1220 tion level) or to consistent to allow any number, as long as it re‐
1221 mains the same within the file.
1222 • indent-sequences defines whether block sequences should be indented
1224 or not (when in a mapping, this indentation is not mandatory -- some
1225 people perceive the - as part of the indentation). Possible values:
1226 true, false, whatever and consistent. consistent requires either all
1227 block sequences to be indented, or none to be. whatever means either
1228 indenting or not indenting individual block sequences is OK.
1229 • check-multi-line-strings defines whether to lint indentation in
1231 multi-line strings. Set to true to enable, false to disable.
1232 Default values (when enabled)
1234 rules:
1236 indentation:
1237 spaces: consistent
1238 indent-sequences: true
1239 check-multi-line-strings: false
1240 Examples
1242 1. With indentation: {spaces: 1}
1244 the following code snippet would PASS:
1246 history:
1248 - name: Unix
1249 date: 1969
1250 - name: Linux
1251 date: 1991
1252 nest:
1253 recurse:
1254 - haystack:
1255 needle
1256 2. With indentation: {spaces: 4}
1258 the following code snippet would PASS:
1260 history:
1262 - name: Unix
1263 date: 1969
1264 - name: Linux
1265 date: 1991
1266 nest:
1267 recurse:
1268 - haystack:
1269 needle
1270 the following code snippet would FAIL:
1272 history:
1274 - name: Unix
1275 date: 1969
1276 - name: Linux
1277 date: 1991
1278 nest:
1279 recurse:
1280 - haystack:
1281 needle
1282 3. With indentation: {spaces: consistent}
1284 the following code snippet would PASS:
1286 history:
1288 - name: Unix
1289 date: 1969
1290 - name: Linux
1291 date: 1991
1292 nest:
1293 recurse:
1294 - haystack:
1295 needle
1296 the following code snippet would FAIL:
1298 some:
1300 Russian:
1301 dolls
1302 4. With indentation: {spaces: 2, indent-sequences: false}
1304 the following code snippet would PASS:
1306 list:
1308 - flying
1309 - spaghetti
1310 - monster
1311 the following code snippet would FAIL:
1313 list:
1315 - flying
1316 - spaghetti
1317 - monster
1318 5. With indentation: {spaces: 2, indent-sequences: whatever}
1320 the following code snippet would PASS:
1322 list:
1324 - flying:
1325 - spaghetti
1326 - monster
1327 - not flying:
1328 - spaghetti
1329 - sauce
1330 6. With indentation: {spaces: 2, indent-sequences: consistent}
1332 the following code snippet would PASS:
1334 - flying:
1336 - spaghetti
1337 - monster
1338 - not flying:
1339 - spaghetti
1340 - sauce
1341 the following code snippet would FAIL:
1343 - flying:
1345 - spaghetti
1346 - monster
1347 - not flying:
1348 - spaghetti
1349 - sauce
1350 7. With indentation: {spaces: 4, check-multi-line-strings: true}
1352 the following code snippet would PASS:
1354 Blaise Pascal:
1356 Je vous écris une longue lettre parce que
1357 je n'ai pas le temps d'en écrire une courte.
1358 the following code snippet would PASS:
1360 Blaise Pascal: Je vous écris une longue lettre parce que
1362 je n'ai pas le temps d'en écrire une courte.
1363 the following code snippet would FAIL:
1365 Blaise Pascal: Je vous écris une longue lettre parce que
1367 je n'ai pas le temps d'en écrire une courte.
1368 the following code snippet would FAIL:
1370 C code:
1372 void main() {
1373 printf("foo");
1374 }
1375 the following code snippet would PASS:
1377 C code:
1379 void main() {
1380 printf("bar");
1381 }
1382 key-duplicates
1384 Use this rule to prevent multiple entries with the same key in map‐
1385 pings.
1386 Examples
1388 1. With key-duplicates: {}
1390 the following code snippet would PASS:
1392 - key 1: v
1394 key 2: val
1395 key 3: value
1396 - {a: 1, b: 2, c: 3}
1397 the following code snippet would FAIL:
1399 - key 1: v
1401 key 2: val
1402 key 1: value
1403 the following code snippet would FAIL:
1405 - {a: 1, b: 2, b: 3}
1407 the following code snippet would FAIL:
1409 duplicated key: 1
1411 "duplicated key": 2
1412 other duplication: 1
1414 ? >-
1415 other
1416 duplication
1417 : 2
1418 key-ordering
1420 Use this rule to enforce alphabetical ordering of keys in mappings. The
1421 sorting order uses the Unicode code point number as a default. As a re‐
1422 sult, the ordering is case-sensitive and not accent-friendly (see exam‐
1423 ples below). This can be changed by setting the global locale option.
1424 This allows one to sort case and accents properly.
1425 Examples
1427 1. With key-ordering: {}
1429 the following code snippet would PASS:
1431 - key 1: v
1433 key 2: val
1434 key 3: value
1435 - {a: 1, b: 2, c: 3}
1436 - T-shirt: 1
1437 T-shirts: 2
1438 t-shirt: 3
1439 t-shirts: 4
1440 - hair: true
1441 hais: true
1442 haïr: true
1443 haïssable: true
1444 the following code snippet would FAIL:
1446 - key 2: v
1448 key 1: val
1449 the following code snippet would FAIL:
1451 - {b: 1, a: 2}
1453 the following code snippet would FAIL:
1455 - T-shirt: 1
1457 t-shirt: 2
1458 T-shirts: 3
1459 t-shirts: 4
1460 the following code snippet would FAIL:
1462 - haïr: true
1464 hais: true
1465 2. With global option locale: "en_US.UTF-8" and rule key-ordering: {}
1467 as opposed to before, the following code snippet would now PASS:
1469 - t-shirt: 1
1471 T-shirt: 2
1472 t-shirts: 3
1473 T-shirts: 4
1474 - hair: true
1475 haïr: true
1476 hais: true
1477 haïssable: true
1478 line-length
1480 Use this rule to set a limit to lines length.
1481 Options
1483 • max defines the maximal (inclusive) length of lines.
1485 • allow-non-breakable-words is used to allow non breakable words (with‐
1487 out spaces inside) to overflow the limit. This is useful for long
1488 URLs, for instance. Use true to allow, false to forbid.
1489 • allow-non-breakable-inline-mappings implies allow-non-breakable-words
1491 and extends it to also allow non-breakable words in inline mappings.
1492 Default values (when enabled)
1494 rules:
1496 line-length:
1497 max: 80
1498 allow-non-breakable-words: true
1499 allow-non-breakable-inline-mappings: false
1500 Examples
1502 1. With line-length: {max: 70}
1504 the following code snippet would PASS:
1506 long sentence:
1508 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
1509 eiusmod tempor incididunt ut labore et dolore magna aliqua.
1510 the following code snippet would FAIL:
1512 long sentence:
1514 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
1515 tempor incididunt ut labore et dolore magna aliqua.
1516 2. With line-length: {max: 60, allow-non-breakable-words: true}
1518 the following code snippet would PASS:
1520 this:
1522 is:
1523 - a:
1524 http://localhost/very/very/very/very/very/very/very/very/long/url
1525 # this comment is too long,
1527 # but hard to split:
1528 # http://localhost/another/very/very/very/very/very/very/very/very/long/url
1529 the following code snippet would FAIL:
1531 - this line is waaaaaaaaaaaaaay too long but could be easily split...
1533 and the following code snippet would also FAIL:
1535 - foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
1537 3. With line-length: {max: 60, allow-non-breakable-words: true, al‐
1539 low-non-breakable-inline-mappings: true}
1540 the following code snippet would PASS:
1542 - foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
1544 4. With line-length: {max: 60, allow-non-breakable-words: false}
1546 the following code snippet would FAIL:
1548 this:
1550 is:
1551 - a:
1552 http://localhost/very/very/very/very/very/very/very/very/long/url
1553 new-line-at-end-of-file
1555 Use this rule to require a new line character (\n) at the end of files.
1556 The POSIX standard requires the last line to end with a new line char‐
1558 acter. All UNIX tools expect a new line at the end of files. Most text
1559 editors use this convention too.
1560 new-lines
1562 Use this rule to force the type of new line characters.
1563 Options
1565 • Set type to unix to enforce UNIX-typed new line characters (\n), set
1567 type to dos to enforce DOS-typed new line characters (\r\n), or set
1568 type to platform to infer the type from the system running yamllint
1569 (\n on POSIX / UNIX / Linux / Mac OS systems or \r\n on DOS / Windows
1570 systems).
1571 Default values (when enabled)
1573 rules:
1575 new-lines:
1576 type: unix
1577 octal-values
1579 Use this rule to prevent values with octal numbers. In YAML, numbers
1580 that start with 0 are interpreted as octal, but this is not always
1581 wanted. For instance 010 is the city code of Beijing, and should not
1582 be converted to 8.
1583 Options
1585 • Use forbid-implicit-octal to prevent numbers starting with 0.
1587 • Use forbid-explicit-octal to prevent numbers starting with 0o.
1589 Default values (when enabled)
1591 rules:
1593 octal-values:
1594 forbid-implicit-octal: true
1595 forbid-explicit-octal: true
1596 Examples
1598 1. With octal-values: {forbid-implicit-octal: true}
1600 the following code snippets would PASS:
1602 user:
1604 city-code: '010'
1605 the following code snippets would PASS:
1607 user:
1609 city-code: 010,021
1610 the following code snippets would FAIL:
1612 user:
1614 city-code: 010
1615 2. With octal-values: {forbid-explicit-octal: true}
1617 the following code snippets would PASS:
1619 user:
1621 city-code: '0o10'
1622 the following code snippets would FAIL:
1624 user:
1626 city-code: 0o10
1627 quoted-strings
1629 Use this rule to forbid any string values that are not quoted, or to
1630 prevent quoted strings without needing it. You can also enforce the
1631 type of the quote used.
1632 Options
1634 • quote-type defines allowed quotes: single, double or any (default).
1636 • required defines whether using quotes in string values is required
1638 (true, default) or not (false), or only allowed when really needed
1639 (only-when-needed).
1640 • extra-required is a list of PCRE regexes to force string values to be
1642 quoted, if they match any regex. This option can only be used with
1643 required: false and required: only-when-needed.
1644 • extra-allowed is a list of PCRE regexes to allow quoted string val‐
1646 ues, even if required: only-when-needed is set.
1647 • allow-quoted-quotes allows (true) using disallowed quotes for strings
1649 with allowed quotes inside. Default false.
1650 Note: Multi-line strings (with | or >) will not be checked.
1652 Default values (when enabled)
1654 rules:
1656 quoted-strings:
1657 quote-type: any
1658 required: true
1659 extra-required: []
1660 extra-allowed: []
1661 allow-quoted-quotes: false
1662 Examples
1664 1. With quoted-strings: {quote-type: any, required: true}
1666 the following code snippet would PASS:
1668 foo: "bar"
1670 bar: 'foo'
1671 number: 123
1672 boolean: true
1673 the following code snippet would FAIL:
1675 foo: bar
1677 2. With quoted-strings: {quote-type: single, required:
1679 only-when-needed}
1680 the following code snippet would PASS:
1682 foo: bar
1684 bar: foo
1685 not_number: '123'
1686 not_boolean: 'true'
1687 not_comment: '# comment'
1688 not_list: '[1, 2, 3]'
1689 not_map: '{a: 1, b: 2}'
1690 the following code snippet would FAIL:
1692 foo: 'bar'
1694 3. With quoted-strings: {required: false, extra-required: [^http://,
1696 ^ftp://]}
1697 the following code snippet would PASS:
1699 - localhost
1701 - "localhost"
1702 - "http://localhost"
1703 - "ftp://localhost"
1704 the following code snippet would FAIL:
1706 - http://localhost
1708 - ftp://localhost
1709 4. With quoted-strings: {required: only-when-needed, extra-allowed:
1711 [^http://, ^ftp://], extra-required: [QUOTED]}
1712 the following code snippet would PASS:
1714 - localhost
1716 - "http://localhost"
1717 - "ftp://localhost"
1718 - "this is a string that needs to be QUOTED"
1719 the following code snippet would FAIL:
1721 - "localhost"
1723 - this is a string that needs to be QUOTED
1724 5. With quoted-strings: {quote-type: double, allow-quoted-quotes:
1726 false}
1727 the following code snippet would PASS:
1729 foo: "bar\"baz"
1731 the following code snippet would FAIL:
1733 foo: 'bar"baz'
1735 6. With quoted-strings: {quote-type: double, allow-quoted-quotes: true}
1737 the following code snippet would PASS:
1739 foo: 'bar"baz'
1741 trailing-spaces
1743 Use this rule to forbid trailing spaces at the end of lines.
1744 Examples
1746 1. With trailing-spaces: {}
1748 the following code snippet would PASS:
1750 this document doesn't contain
1752 any trailing
1753 spaces
1754 the following code snippet would FAIL:
1756 this document contains
1758 trailing spaces
1759 on lines 1 and 3
1760 truthy
1762 Use this rule to forbid non-explicitly typed truthy values other than
1763 allowed ones (by default: true and false), for example YES or off.
1764 This can be useful to prevent surprises from YAML parsers transforming
1766 [yes, FALSE, Off] into [true, false, false] or {y: 1, yes: 2, on: 3,
1767 true: 4, True: 5} into {y: 1, true: 5}.
1768 Options
1770 • allowed-values defines the list of truthy values which will be ig‐
1772 nored during linting. The default is ['true', 'false'], but can be
1773 changed to any list containing: 'TRUE', 'True', 'true', 'FALSE',
1774 'False', 'false', 'YES', 'Yes', 'yes', 'NO', 'No', 'no', 'ON', 'On',
1775 'on', 'OFF', 'Off', 'off'.
1776 • check-keys disables verification for keys in mappings. By default,
1778 truthy rule applies to both keys and values. Set this option to false
1779 to prevent this.
1780 Default values (when enabled)
1782 rules:
1784 truthy:
1785 allowed-values: ['true', 'false']
1786 check-keys: true
1787 Examples
1789 1. With truthy: {}
1791 the following code snippet would PASS:
1793 boolean: true
1795 object: {"True": 1, 1: "True"}
1797 "yes": 1
1799 "on": 2
1800 "True": 3
1801 explicit:
1803 string1: !!str True
1804 string2: !!str yes
1805 string3: !!str off
1806 encoded: !!binary |
1807 True
1808 OFF
1809 pad== # this decodes as 'N»8Qii'
1810 boolean1: !!bool true
1811 boolean2: !!bool "false"
1812 boolean3: !!bool FALSE
1813 boolean4: !!bool True
1814 boolean5: !!bool off
1815 boolean6: !!bool NO
1816 the following code snippet would FAIL:
1818 object: {True: 1, 1: True}
1820 the following code snippet would FAIL:
1822 yes: 1
1824 on: 2
1825 True: 3
1826 2. With truthy: {allowed-values: ["yes", "no"]}
1828 the following code snippet would PASS:
1830 - yes
1832 - no
1833 - "true"
1834 - 'false'
1835 - foo
1836 - bar
1837 the following code snippet would FAIL:
1839 - true
1841 - false
1842 - on
1843 - off
1844 3. With truthy: {check-keys: false}
1846 the following code snippet would PASS:
1848 yes: 1
1850 on: 2
1851 true: 3
1852 the following code snippet would FAIL:
1854 yes: Yes
1856 on: On
1857 true: True
1858 Disable with comments
1860 Disabling checks for a specific line
1861 To prevent yamllint from reporting problems for a specific line, add a
1862 directive comment (# yamllint disable-line ...) on that line, or on the
1863 line above. For instance:
1864 # The following mapping contains the same key twice,
1866 # but I know what I'm doing:
1867 key: value 1
1868 key: value 2 # yamllint disable-line rule:key-duplicates
1869 - This line is waaaaaaaaaay too long but yamllint will not report anything about it. # yamllint disable-line rule:line-length
1871 This line will be checked by yamllint.
1872 or:
1874 # The following mapping contains the same key twice,
1876 # but I know what I'm doing:
1877 key: value 1
1878 # yamllint disable-line rule:key-duplicates
1879 key: value 2
1880 # yamllint disable-line rule:line-length
1882 - This line is waaaaaaaaaay too long but yamllint will not report anything about it.
1883 This line will be checked by yamllint.
1884 It is possible, although not recommend, to disabled all rules for a
1886 specific line:
1887 # yamllint disable-line
1889 - { all : rules ,are disabled for this line}
1890 You can't make yamllint ignore invalid YAML syntax on a line (which
1892 generates a syntax error), such as when templating a YAML file with
1893 Jinja. In some cases, you can workaround this by putting the templating
1894 syntax in a YAML comment. See Putting template flow control in com‐
1895 ments.
1896 If you need to disable multiple rules, it is allowed to chain rules
1898 like this: # yamllint disable-line rule:hyphens rule:commas rule:inden‐
1899 tation.
1900 Disabling checks for all (or part of) the file
1902 To prevent yamllint from reporting problems for the whole file, or for
1903 a block of lines within the file, use # yamllint disable ... and # yam‐
1904 llint enable ... directive comments. For instance:
1905 # yamllint disable rule:colons
1907 - Lorem : ipsum
1908 dolor : sit amet,
1909 consectetur : adipiscing elit
1910 # yamllint enable rule:colons
1911 - rest of the document...
1913 It is possible, although not recommend, to disabled all rules:
1915 # yamllint disable
1917 - Lorem :
1918 ipsum:
1919 dolor : [ sit,amet]
1920 - consectetur : adipiscing elit
1921 # yamllint enable
1922 If you need to disable multiple rules, it is allowed to chain rules
1924 like this: # yamllint disable rule:hyphens rule:commas rule:indenta‐
1925 tion.
1926 Disabling all checks for a file
1928 To prevent yamllint from reporting problems for a specific file, add
1929 the directive comment # yamllint disable-file as the first line of the
1930 file. For instance:
1931 # yamllint disable-file
1933 # The following mapping contains the same key twice, but I know what I'm doing:
1934 key: value 1
1935 key: value 2
1936 - This line is waaaaaaaaaay too long but yamllint will not report anything about it.
1938 or:
1940 # yamllint disable-file
1942 # This file is not valid YAML because it is a Jinja template
1943 {% if extra_info %}
1944 key1: value1
1945 {% endif %}
1946 key2: value2
1947 Putting template flow control in comments
1949 Alternatively for templating you can wrap the template statements in
1950 comments to make it a valid YAML file. As long as the templating lan‐
1951 guage doesn't use the same comment symbol, it should be a valid tem‐
1952 plate and valid YAML (pre and post-template processing).
1953 Example of a Jinja2 code that cannot be parsed as YAML because it con‐
1955 tains invalid tokens {% and %}:
1956 # This file IS NOT valid YAML and will produce syntax errors
1958 {% if extra_info %}
1959 key1: value1
1960 {% endif %}
1961 key2: value2
1962 But it can be fixed using YAML comments:
1964 # This file IS valid YAML because the Jinja is in a YAML comment
1966 # {% if extra_info %}
1967 key1: value1
1968 # {% endif %}
1969 key2: value2
1970 Development
1972 yamllint provides both a script and a Python module. The latter can be
1973 used to write your own linting tools.
1974 Basic example of running the linter from Python:
1976 import yamllint
1978 yaml_config = yamllint.config.YamlLintConfig("extends: default")
1980 for p in yamllint.linter.run("example.yaml", yaml_config):
1981 print(p.desc, p.line, p.rule)
1982 class yamllint.linter.LintProblem(line, column, desc='<no descrip‐
1984 tion>', rule=None)
1985 Represents a linting problem found by yamllint.
1986 column Column on which the problem was found (starting at 1)
1988 desc Human-readable description of the problem
1990 line Line on which the problem was found (starting at 1)
1992 rule Identifier of the rule that detected the problem
1994 yamllint.linter.run(input, conf, filepath=None)
1996 Lints a YAML source.
1997 Returns a generator of LintProblem objects.
1999 Parameters
2001 • input -- buffer, string or stream to read from
2003 • conf -- yamllint configuration object
2005 Integration with text editors
2007 Most text editors support syntax checking and highlighting, to visually
2008 report syntax errors and warnings to the user. yamllint can be used to
2009 syntax-check YAML source, but a bit of configuration is required de‐
2010 pending on your favorite text editor.
2011 Vim
2013 Assuming that the ALE plugin is installed, yamllint is supported by de‐
2014 fault. It is automatically enabled when editing YAML files.
2015 If you instead use the syntastic plugin, add this to your .vimrc:
2017 let g:syntastic_yaml_checkers = ['yamllint']
2019 Neovim
2021 Assuming that the neomake plugin is installed, yamllint is supported by
2022 default. It is automatically enabled when editing YAML files.
2023 Emacs
2025 If you are flycheck user, you can use flycheck-yamllint integration.
2026 Visual Studio Code
2028 https://marketplace.visualstudio.com/items?itemName=fnando.linter
2029 IntelliJ
2031 https://plugins.jetbrains.com/plugin/15349-yamllint
2032 Other text editors
2034 Help wanted!
2035 Your favorite text editor is not listed here? Help us improve by adding
2037 a section (by opening a pull-request or issue on GitHub).
2038 Integration with other software
2040 Integration with pre-commit
2041 You can integrate yamllint in pre-commit tool. Here is an example, to
2042 add in your .pre-commit-config.yaml
2043 ---
2045 # Update the rev variable with the release version that you want, from the yamllint repo
2046 # You can pass your custom .yamllint with args attribute.
2047 - repo: https://github.com/adrienverge/yamllint.git
2048 rev: v1.17.0
2049 hooks:
2050 - id: yamllint
2051 args: [-c=/path/to/.yamllint]
2052 Integration with GitHub Actions
2054 yamllint auto-detects when it's running inside of GitHub Actions and
2055 automatically uses the suited output format to decorate code with lint‐
2056 ing errors. You can also force the GitHub Actions output with yamllint
2057 --format github.
2058 A minimal example workflow using GitHub Actions:
2060 ---
2062 on: push # yamllint disable-line rule:truthy
2063 jobs:
2065 lint:
2066 runs-on: ubuntu-latest
2067 steps:
2068 - uses: actions/checkout@v3
2069 - name: Install yamllint
2071 run: pip install yamllint
2072 - name: Lint YAML files
2074 run: yamllint .
2075 Integration with Arcanist
2077 You can configure yamllint to run on arc lint. Here is an example .ar‐
2078 clint file that makes use of this configuration.
2079 {
2081 "linters": {
2082 "yamllint": {
2083 "type": "script-and-regex",
2084 "script-and-regex.script": "yamllint",
2085 "script-and-regex.regex": "/^(?P<line>\\d+):(?P<offset>\\d+) +(?P<severity>warning|error) +(?P<message>.*) +\\((?P<name>.*)\\)$/m",
2086 "include": "(\\.(yml|yaml)$)"
2087 }
2088 }
2089 }
2090
2092 Adrien Vergé
2093
2095 2023, Adrien Vergé
20961.29.0 Jan 10, 2023 YAMLLINT(1)