1YAMLLINT(1) yamllint YAMLLINT(1)
2
6 yamllint -
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
49 directory:
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 · .yamllint, .yamllint.yaml or .yamllint.yml in the current working
118 directory
119 · the file referenced by $YAMLLINT_CONFIG_FILE, if set
121 · $XDG_CONFIG_HOME/yamllint/config
123 · ~/.config/yamllint/config
125 Finally if no config file is found, the default configuration is
127 applied.
128 Default configuration
130 Unless told otherwise, yamllint uses its default configuration:
131 ---
133 yaml-files:
135 - '*.yaml'
136 - '*.yml'
137 - '.yamllint'
138 rules:
140 braces: enable
141 brackets: enable
142 colons: enable
143 commas: enable
144 comments:
145 level: warning
146 comments-indentation:
147 level: warning
148 document-end: disable
149 document-start:
150 level: warning
151 empty-lines: enable
152 empty-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
210 already-existing 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:
247 default or relaxed) or a serialized YAML object describing the configu‐
248 ration.
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 Ignoring paths
287 It is possible to exclude specific files or directories, so that the
288 linter doesn't process them.
289 You can either totally ignore files (they won't be looked at):
291 extends: default
293 ignore: |
295 /this/specific/file.yaml
296 all/this/directory/
297 *.template.yaml
298 or ignore paths only for specific rules:
300 extends: default
302 rules:
304 trailing-spaces:
305 ignore: |
306 /this-file-has-trailing-spaces-but-it-is-OK.yaml
307 /generated/*.yaml
308 Note that this .gitignore-style path pattern allows complex path exclu‐
310 sion/inclusion, see the pathspec README file for more details. Here is
311 a more complex example:
312 # For all rules
314 ignore: |
315 *.dont-lint-me.yaml
316 /bin/
317 !/bin/*.lint-me-anyway.yaml
318 extends: default
320 rules:
322 key-duplicates:
323 ignore: |
324 generated
325 *.template.yaml
326 trailing-spaces:
327 ignore: |
328 *.ignore-trailing-spaces.yaml
329 ascii-art/*
330 Setting the locale
332 It is possible to set the locale option globally. This is passed to
333 Python's locale.setlocale, so an empty string "" will use the system
334 default locale, while e.g. "en_US.UTF-8" will use that.
335 Currently this only affects the key-ordering rule. The default will
337 order by Unicode code point number, while locales will sort case and
338 accents properly as well.
339 extends: default
341 locale: en_US.UTF-8
343 Rules
345 When linting a document with yamllint, a series of rules (such as
346 line-length, trailing-spaces, etc.) are checked against.
347 A configuration file can be used to enable or disable these rules, to
349 set their level (error or warning), but also to tweak their options.
350 This page describes the rules and their options.
352 List of rules
354 · braces
355 · brackets
357 · colons
359 · commas
361 · comments
363 · comments-indentation
365 · document-end
367 · document-start
369 · empty-lines
371 · empty-values
373 · hyphens
375 · indentation
377 · key-duplicates
379 · key-ordering
381 · line-length
383 · new-line-at-end-of-file
385 · new-lines
387 · octal-values
389 · quoted-strings
391 · trailing-spaces
393 · truthy
395 braces
397 Use this rule to control the use of flow mappings or number of spaces
398 inside braces ({ and }).
399 Options
401 · forbid is used to forbid the use of flow mappings which are denoted
403 by surrounding braces ({ and }). Use true to forbid the use of flow
404 mappings completely. Use non-empty to forbid the use of all flow map‐
405 pings except for empty ones.
406 · min-spaces-inside defines the minimal number of spaces required
408 inside braces.
409 · max-spaces-inside defines the maximal number of spaces allowed inside
411 braces.
412 · min-spaces-inside-empty defines the minimal number of spaces required
414 inside empty braces.
415 · max-spaces-inside-empty defines the maximal number of spaces allowed
417 inside empty braces.
418 Default values (when enabled)
420 rules:
422 braces:
423 forbid: false
424 min-spaces-inside: 0
425 max-spaces-inside: 0
426 min-spaces-inside-empty: -1
427 max-spaces-inside-empty: -1
428 Examples
430 1. With braces: {forbid: true}
432 the following code snippet would PASS:
434 object:
436 key1: 4
437 key2: 8
438 the following code snippet would FAIL:
440 object: { key1: 4, key2: 8 }
442 2. With braces: {forbid: non-empty}
444 the following code snippet would PASS:
446 object: {}
448 the following code snippet would FAIL:
450 object: { key1: 4, key2: 8 }
452 3. With braces: {min-spaces-inside: 0, max-spaces-inside: 0}
454 the following code snippet would PASS:
456 object: {key1: 4, key2: 8}
458 the following code snippet would FAIL:
460 object: { key1: 4, key2: 8 }
462 4. With braces: {min-spaces-inside: 1, max-spaces-inside: 3}
464 the following code snippet would PASS:
466 object: { key1: 4, key2: 8 }
468 the following code snippet would PASS:
470 object: { key1: 4, key2: 8 }
472 the following code snippet would FAIL:
474 object: { key1: 4, key2: 8 }
476 the following code snippet would FAIL:
478 object: {key1: 4, key2: 8 }
480 5. With braces: {min-spaces-inside-empty: 0, max-spaces-inside-empty:
482 0}
483 the following code snippet would PASS:
485 object: {}
487 the following code snippet would FAIL:
489 object: { }
491 6. With braces: {min-spaces-inside-empty: 1, max-spaces-inside-empty:
493 -1}
494 the following code snippet would PASS:
496 object: { }
498 the following code snippet would FAIL:
500 object: {}
502 brackets
504 Use this rule to control the use of flow sequences or the number of
505 spaces inside brackets ([ and ]).
506 Options
508 · forbid is used to forbid the use of flow sequences which are denoted
510 by surrounding brackets ([ and ]). Use true to forbid the use of flow
511 sequences completely. Use non-empty to forbid the use of all flow
512 sequences except for empty ones.
513 · min-spaces-inside defines the minimal number of spaces required
515 inside brackets.
516 · max-spaces-inside defines the maximal number of spaces allowed inside
518 brackets.
519 · min-spaces-inside-empty defines the minimal number of spaces required
521 inside empty brackets.
522 · max-spaces-inside-empty defines the maximal number of spaces allowed
524 inside empty brackets.
525 Default values (when enabled)
527 rules:
529 brackets:
530 forbid: false
531 min-spaces-inside: 0
532 max-spaces-inside: 0
533 min-spaces-inside-empty: -1
534 max-spaces-inside-empty: -1
535 Examples
537 1. With brackets: {forbid: true}
539 the following code snippet would PASS:
541 object:
543 - 1
544 - 2
545 - abc
546 the following code snippet would FAIL:
548 object: [ 1, 2, abc ]
550 2. With brackets: {forbid: non-empty}
552 the following code snippet would PASS:
554 object: []
556 the following code snippet would FAIL:
558 object: [ 1, 2, abc ]
560 3. With brackets: {min-spaces-inside: 0, max-spaces-inside: 0}
562 the following code snippet would PASS:
564 object: [1, 2, abc]
566 the following code snippet would FAIL:
568 object: [ 1, 2, abc ]
570 4. With brackets: {min-spaces-inside: 1, max-spaces-inside: 3}
572 the following code snippet would PASS:
574 object: [ 1, 2, abc ]
576 the following code snippet would PASS:
578 object: [ 1, 2, abc ]
580 the following code snippet would FAIL:
582 object: [ 1, 2, abc ]
584 the following code snippet would FAIL:
586 object: [1, 2, abc ]
588 5. With brackets: {min-spaces-inside-empty: 0, max-spaces-inside-empty:
590 0}
591 the following code snippet would PASS:
593 object: []
595 the following code snippet would FAIL:
597 object: [ ]
599 6. With brackets: {min-spaces-inside-empty: 1, max-spaces-inside-empty:
601 -1}
602 the following code snippet would PASS:
604 object: [ ]
606 the following code snippet would FAIL:
608 object: []
610 colons
612 Use this rule to control the number of spaces before and after colons
613 (:).
614 Options
616 · max-spaces-before defines the maximal number of spaces allowed before
618 colons (use -1 to disable).
619 · max-spaces-after defines the maximal number of spaces allowed after
621 colons (use -1 to disable).
622 Default values (when enabled)
624 rules:
626 colons:
627 max-spaces-before: 0
628 max-spaces-after: 1
629 Examples
631 1. With colons: {max-spaces-before: 0, max-spaces-after: 1}
633 the following code snippet would PASS:
635 object:
637 - a
638 - b
639 key: value
640 2. With colons: {max-spaces-before: 1}
642 the following code snippet would PASS:
644 object :
646 - a
647 - b
648 the following code snippet would FAIL:
650 object :
652 - a
653 - b
654 3. With colons: {max-spaces-after: 2}
656 the following code snippet would PASS:
658 first: 1
660 second: 2
661 third: 3
662 the following code snippet would FAIL:
664 first: 1
666 2nd: 2
667 third: 3
668 commas
670 Use this rule to control the number of spaces before and after commas
671 (,).
672 Options
674 · max-spaces-before defines the maximal number of spaces allowed before
676 commas (use -1 to disable).
677 · min-spaces-after defines the minimal number of spaces required after
679 commas.
680 · max-spaces-after defines the maximal number of spaces allowed after
682 commas (use -1 to disable).
683 Default values (when enabled)
685 rules:
687 commas:
688 max-spaces-before: 0
689 min-spaces-after: 1
690 max-spaces-after: 1
691 Examples
693 1. With commas: {max-spaces-before: 0}
695 the following code snippet would PASS:
697 strange var:
699 [10, 20, 30, {x: 1, y: 2}]
700 the following code snippet would FAIL:
702 strange var:
704 [10, 20 , 30, {x: 1, y: 2}]
705 2. With commas: {max-spaces-before: 2}
707 the following code snippet would PASS:
709 strange var:
711 [10 , 20 , 30, {x: 1 , y: 2}]
712 3. With commas: {max-spaces-before: -1}
714 the following code snippet would PASS:
716 strange var:
718 [10,
719 20 , 30
720 , {x: 1, y: 2}]
721 4. With commas: {min-spaces-after: 1, max-spaces-after: 1}
723 the following code snippet would PASS:
725 strange var:
727 [10, 20, 30, {x: 1, y: 2}]
728 the following code snippet would FAIL:
730 strange var:
732 [10, 20,30, {x: 1, y: 2}]
733 5. With commas: {min-spaces-after: 1, max-spaces-after: 3}
735 the following code snippet would PASS:
737 strange var:
739 [10, 20, 30, {x: 1, y: 2}]
740 6. With commas: {min-spaces-after: 0, max-spaces-after: 1}
742 the following code snippet would PASS:
744 strange var:
746 [10, 20,30, {x: 1, y: 2}]
747 comments
749 Use this rule to control the position and formatting of comments.
750 Options
752 · Use require-starting-space to require a space character right after
754 the #. Set to true to enable, false to disable.
755 · Use ignore-shebangs to ignore a shebang at the beginning of the file
757 when require-starting-space is set.
758 · min-spaces-from-content is used to visually separate inline comments
760 from content. It defines the minimal required number of spaces
761 between a comment and its preceding content.
762 Default values (when enabled)
764 rules:
766 comments:
767 require-starting-space: true
768 ignore-shebangs: true
769 min-spaces-from-content: 2
770 Examples
772 1. With comments: {require-starting-space: true}
774 the following code snippet would PASS:
776 # This sentence
778 # is a block comment
779 the following code snippet would PASS:
781 ##############################
783 ## This is some documentation
784 the following code snippet would FAIL:
786 #This sentence
788 #is a block comment
789 2. With comments: {min-spaces-from-content: 2}
791 the following code snippet would PASS:
793 x = 2 ^ 127 - 1 # Mersenne prime number
795 the following code snippet would FAIL:
797 x = 2 ^ 127 - 1 # Mersenne prime number
799 comments-indentation
801 Use this rule to force comments to be indented like content.
802 Examples
804 1. With comments-indentation: {}
806 the following code snippet would PASS:
808 # Fibonacci
810 [0, 1, 1, 2, 3, 5]
811 the following code snippet would FAIL:
813 # Fibonacci
815 [0, 1, 1, 2, 3, 5]
816 the following code snippet would PASS:
818 list:
820 - 2
821 - 3
822 # - 4
823 - 5
824 the following code snippet would FAIL:
826 list:
828 - 2
829 - 3
830 # - 4
831 - 5
832 the following code snippet would PASS:
834 # This is the first object
836 obj1:
837 - item A
838 # - item B
839 # This is the second object
840 obj2: []
841 the following code snippet would PASS:
843 # This sentence
845 # is a block comment
846 the following code snippet would FAIL:
848 # This sentence
850 # is a block comment
851 document-end
853 Use this rule to require or forbid the use of document end marker
854 (...).
855 Options
857 · Set present to true when the document end marker is required, or to
859 false when it is forbidden.
860 Default values (when enabled)
862 rules:
864 document-end:
865 present: true
866 Examples
868 1. With document-end: {present: true}
870 the following code snippet would PASS:
872 ---
874 this:
875 is: [a, document]
876 ...
877 ---
878 - this
879 - is: another one
880 ...
881 the following code snippet would FAIL:
883 ---
885 this:
886 is: [a, document]
887 ---
888 - this
889 - is: another one
890 ...
891 2. With document-end: {present: false}
893 the following code snippet would PASS:
895 ---
897 this:
898 is: [a, document]
899 ---
900 - this
901 - is: another one
902 the following code snippet would FAIL:
904 ---
906 this:
907 is: [a, document]
908 ...
909 ---
910 - this
911 - is: another one
912 document-start
914 Use this rule to require or forbid the use of document start marker
915 (---).
916 Options
918 · Set present to true when the document start marker is required, or to
920 false when it is forbidden.
921 Default values (when enabled)
923 rules:
925 document-start:
926 present: true
927 Examples
929 1. With document-start: {present: true}
931 the following code snippet would PASS:
933 ---
935 this:
936 is: [a, document]
937 ---
938 - this
939 - is: another one
940 the following code snippet would FAIL:
942 this:
944 is: [a, document]
945 ---
946 - this
947 - is: another one
948 2. With document-start: {present: false}
950 the following code snippet would PASS:
952 this:
954 is: [a, document]
955 ...
956 the following code snippet would FAIL:
958 ---
960 this:
961 is: [a, document]
962 ...
963 empty-lines
965 Use this rule to set a maximal number of allowed consecutive blank
966 lines.
967 Options
969 · max defines the maximal number of empty lines allowed in the docu‐
971 ment.
972 · max-start defines the maximal number of empty lines allowed at the
974 beginning of the file. This option takes precedence over max.
975 · max-end defines the maximal number of empty lines allowed at the end
977 of the file. This option takes precedence over max.
978 Default values (when enabled)
980 rules:
982 empty-lines:
983 max: 2
984 max-start: 0
985 max-end: 0
986 Examples
988 1. With empty-lines: {max: 1}
990 the following code snippet would PASS:
992 - foo:
994 - 1
995 - 2
996 - bar: [3, 4]
998 the following code snippet would FAIL:
1000 - foo:
1002 - 1
1003 - 2
1004 - bar: [3, 4]
1007 empty-values
1009 Use this rule to prevent nodes with empty content, that implicitly
1010 result in null values.
1011 Options
1013 · Use forbid-in-block-mappings to prevent empty values in block map‐
1015 pings.
1016 · Use forbid-in-flow-mappings to prevent empty values in flow mappings.
1018 Default values (when enabled)
1020 rules:
1022 empty-values:
1023 forbid-in-block-mappings: true
1024 forbid-in-flow-mappings: true
1025 Examples
1027 1. With empty-values: {forbid-in-block-mappings: true}
1029 the following code snippets would PASS:
1031 some-mapping:
1033 sub-element: correctly indented
1034 explicitly-null: null
1036 the following code snippets would FAIL:
1038 some-mapping:
1040 sub-element: incorrectly indented
1041 implicitly-null:
1043 2. With empty-values: {forbid-in-flow-mappings: true}
1045 the following code snippet would PASS:
1047 {prop: null}
1049 {a: 1, b: 2, c: 3}
1050 the following code snippets would FAIL:
1052 {prop: }
1054 {a: 1, b:, c: 3}
1056 hyphens
1058 Use this rule to control the number of spaces after hyphens (-).
1059 Options
1061 · max-spaces-after defines the maximal number of spaces allowed after
1063 hyphens.
1064 Default values (when enabled)
1066 rules:
1068 hyphens:
1069 max-spaces-after: 1
1070 Examples
1072 1. With hyphens: {max-spaces-after: 1}
1074 the following code snippet would PASS:
1076 - first list:
1078 - a
1079 - b
1080 - - 1
1081 - 2
1082 - 3
1083 the following code snippet would FAIL:
1085 - first list:
1087 - a
1088 - b
1089 the following code snippet would FAIL:
1091 - - 1
1093 - 2
1094 - 3
1095 2. With hyphens: {max-spaces-after: 3}
1097 the following code snippet would PASS:
1099 - key
1101 - key2
1102 - key42
1103 the following code snippet would FAIL:
1105 - key
1107 - key2
1108 - key42
1109 indentation
1111 Use this rule to control the indentation.
1112 Options
1114 · spaces defines the indentation width, in spaces. Set either to an
1116 integer (e.g. 2 or 4, representing the number of spaces in an inden‐
1117 tation level) or to consistent to allow any number, as long as it
1118 remains the same within the file.
1119 · indent-sequences defines whether block sequences should be indented
1121 or not (when in a mapping, this indentation is not mandatory -- some
1122 people perceive the - as part of the indentation). Possible values:
1123 true, false, whatever and consistent. consistent requires either all
1124 block sequences to be indented, or none to be. whatever means either
1125 indenting or not indenting individual block sequences is OK.
1126 · check-multi-line-strings defines whether to lint indentation in
1128 multi-line strings. Set to true to enable, false to disable.
1129 Default values (when enabled)
1131 rules:
1133 indentation:
1134 spaces: consistent
1135 indent-sequences: true
1136 check-multi-line-strings: false
1137 Examples
1139 1. With indentation: {spaces: 1}
1141 the following code snippet would PASS:
1143 history:
1145 - name: Unix
1146 date: 1969
1147 - name: Linux
1148 date: 1991
1149 nest:
1150 recurse:
1151 - haystack:
1152 needle
1153 2. With indentation: {spaces: 4}
1155 the following code snippet would PASS:
1157 history:
1159 - name: Unix
1160 date: 1969
1161 - name: Linux
1162 date: 1991
1163 nest:
1164 recurse:
1165 - haystack:
1166 needle
1167 the following code snippet would FAIL:
1169 history:
1171 - name: Unix
1172 date: 1969
1173 - name: Linux
1174 date: 1991
1175 nest:
1176 recurse:
1177 - haystack:
1178 needle
1179 3. With indentation: {spaces: consistent}
1181 the following code snippet would PASS:
1183 history:
1185 - name: Unix
1186 date: 1969
1187 - name: Linux
1188 date: 1991
1189 nest:
1190 recurse:
1191 - haystack:
1192 needle
1193 the following code snippet would FAIL:
1195 some:
1197 Russian:
1198 dolls
1199 4. With indentation: {spaces: 2, indent-sequences: false}
1201 the following code snippet would PASS:
1203 list:
1205 - flying
1206 - spaghetti
1207 - monster
1208 the following code snippet would FAIL:
1210 list:
1212 - flying
1213 - spaghetti
1214 - monster
1215 5. With indentation: {spaces: 2, indent-sequences: whatever}
1217 the following code snippet would PASS:
1219 list:
1221 - flying:
1222 - spaghetti
1223 - monster
1224 - not flying:
1225 - spaghetti
1226 - sauce
1227 6. With indentation: {spaces: 2, indent-sequences: consistent}
1229 the following code snippet would PASS:
1231 - flying:
1233 - spaghetti
1234 - monster
1235 - not flying:
1236 - spaghetti
1237 - sauce
1238 the following code snippet would FAIL:
1240 - flying:
1242 - spaghetti
1243 - monster
1244 - not flying:
1245 - spaghetti
1246 - sauce
1247 7. With indentation: {spaces: 4, check-multi-line-strings: true}
1249 the following code snippet would PASS:
1251 Blaise Pascal:
1253 Je vous écris une longue lettre parce que
1254 je n'ai pas le temps d'en écrire une courte.
1255 the following code snippet would PASS:
1257 Blaise Pascal: Je vous écris une longue lettre parce que
1259 je n'ai pas le temps d'en écrire une courte.
1260 the following code snippet would FAIL:
1262 Blaise Pascal: Je vous écris une longue lettre parce que
1264 je n'ai pas le temps d'en écrire une courte.
1265 the following code snippet would FAIL:
1267 C code:
1269 void main() {
1270 printf("foo");
1271 }
1272 the following code snippet would PASS:
1274 C code:
1276 void main() {
1277 printf("bar");
1278 }
1279 key-duplicates
1281 Use this rule to prevent multiple entries with the same key in map‐
1282 pings.
1283 Examples
1285 1. With key-duplicates: {}
1287 the following code snippet would PASS:
1289 - key 1: v
1291 key 2: val
1292 key 3: value
1293 - {a: 1, b: 2, c: 3}
1294 the following code snippet would FAIL:
1296 - key 1: v
1298 key 2: val
1299 key 1: value
1300 the following code snippet would FAIL:
1302 - {a: 1, b: 2, b: 3}
1304 the following code snippet would FAIL:
1306 duplicated key: 1
1308 "duplicated key": 2
1309 other duplication: 1
1311 ? >-
1312 other
1313 duplication
1314 : 2
1315 key-ordering
1317 Use this rule to enforce alphabetical ordering of keys in mappings. The
1318 sorting order uses the Unicode code point number as a default. As a
1319 result, the ordering is case-sensitive and not accent-friendly (see
1320 examples below). This can be changed by setting the global locale
1321 option. This allows to sort case and accents properly.
1322 Examples
1324 1. With key-ordering: {}
1326 the following code snippet would PASS:
1328 - key 1: v
1330 key 2: val
1331 key 3: value
1332 - {a: 1, b: 2, c: 3}
1333 - T-shirt: 1
1334 T-shirts: 2
1335 t-shirt: 3
1336 t-shirts: 4
1337 - hair: true
1338 hais: true
1339 haïr: true
1340 haïssable: true
1341 the following code snippet would FAIL:
1343 - key 2: v
1345 key 1: val
1346 the following code snippet would FAIL:
1348 - {b: 1, a: 2}
1350 the following code snippet would FAIL:
1352 - T-shirt: 1
1354 t-shirt: 2
1355 T-shirts: 3
1356 t-shirts: 4
1357 the following code snippet would FAIL:
1359 - haïr: true
1361 hais: true
1362 2. With global option locale: "en_US.UTF-8" and rule key-ordering: {}
1364 as opposed to before, the following code snippet would now PASS:
1366 - t-shirt: 1
1368 T-shirt: 2
1369 t-shirts: 3
1370 T-shirts: 4
1371 - hair: true
1372 haïr: true
1373 hais: true
1374 haïssable: true
1375 line-length
1377 Use this rule to set a limit to lines length.
1378 Options
1380 · max defines the maximal (inclusive) length of lines.
1382 · allow-non-breakable-words is used to allow non breakable words (with‐
1384 out spaces inside) to overflow the limit. This is useful for long
1385 URLs, for instance. Use true to allow, false to forbid.
1386 · allow-non-breakable-inline-mappings implies allow-non-breakable-words
1388 and extends it to also allow non-breakable words in inline mappings.
1389 Default values (when enabled)
1391 rules:
1393 line-length:
1394 max: 80
1395 allow-non-breakable-words: true
1396 allow-non-breakable-inline-mappings: false
1397 Examples
1399 1. With line-length: {max: 70}
1401 the following code snippet would PASS:
1403 long sentence:
1405 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
1406 eiusmod tempor incididunt ut labore et dolore magna aliqua.
1407 the following code snippet would FAIL:
1409 long sentence:
1411 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
1412 tempor incididunt ut labore et dolore magna aliqua.
1413 2. With line-length: {max: 60, allow-non-breakable-words: true}
1415 the following code snippet would PASS:
1417 this:
1419 is:
1420 - a:
1421 http://localhost/very/very/very/very/very/very/very/very/long/url
1422 # this comment is too long,
1424 # but hard to split:
1425 # http://localhost/another/very/very/very/very/very/very/very/very/long/url
1426 the following code snippet would FAIL:
1428 - this line is waaaaaaaaaaaaaay too long but could be easily split...
1430 and the following code snippet would also FAIL:
1432 - foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
1434 3. With line-length: {max: 60, allow-non-breakable-words: true,
1436 allow-non-breakable-inline-mappings: true}
1437 the following code snippet would PASS:
1439 - foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
1441 4. With line-length: {max: 60, allow-non-breakable-words: false}
1443 the following code snippet would FAIL:
1445 this:
1447 is:
1448 - a:
1449 http://localhost/very/very/very/very/very/very/very/very/long/url
1450 new-line-at-end-of-file
1452 Use this rule to require a new line character (\n) at the end of files.
1453 The POSIX standard requires the last line to end with a new line char‐
1455 acter. All UNIX tools expect a new line at the end of files. Most text
1456 editors use this convention too.
1457 new-lines
1459 Use this rule to force the type of new line characters.
1460 Options
1462 · Set type to unix to use UNIX-typed new line characters (\n), or dos
1464 to use DOS-typed new line characters (\r\n).
1465 Default values (when enabled)
1467 rules:
1469 new-lines:
1470 type: unix
1471 octal-values
1473 Use this rule to prevent values with octal numbers. In YAML, numbers
1474 that start with 0 are interpreted as octal, but this is not always
1475 wanted. For instance 010 is the city code of Beijing, and should not
1476 be converted to 8.
1477 Options
1479 · Use forbid-implicit-octal to prevent numbers starting with 0.
1481 · Use forbid-explicit-octal to prevent numbers starting with 0o.
1483 Default values (when enabled)
1485 rules:
1487 octal-values:
1488 forbid-implicit-octal: true
1489 forbid-explicit-octal: true
1490 Examples
1492 1. With octal-values: {forbid-implicit-octal: true}
1494 the following code snippets would PASS:
1496 user:
1498 city-code: '010'
1499 the following code snippets would PASS:
1501 user:
1503 city-code: 010,021
1504 the following code snippets would FAIL:
1506 user:
1508 city-code: 010
1509 2. With octal-values: {forbid-explicit-octal: true}
1511 the following code snippets would PASS:
1513 user:
1515 city-code: '0o10'
1516 the following code snippets would FAIL:
1518 user:
1520 city-code: 0o10
1521 quoted-strings
1523 Use this rule to forbid any string values that are not quoted, or to
1524 prevent quoted strings without needing it. You can also enforce the
1525 type of the quote used.
1526 Options
1528 · quote-type defines allowed quotes: single, double or any (default).
1530 · required defines whether using quotes in string values is required
1532 (true, default) or not (false), or only allowed when really needed
1533 (only-when-needed).
1534 · extra-required is a list of PCRE regexes to force string values to be
1536 quoted, if they match any regex. This option can only be used with
1537 required: false and required: only-when-needed.
1538 · extra-allowed is a list of PCRE regexes to allow quoted string val‐
1540 ues, even if required: only-when-needed is set.
1541 Note: Multi-line strings (with | or >) will not be checked.
1543 Default values (when enabled)
1545 rules:
1547 quoted-strings:
1548 quote-type: any
1549 required: true
1550 extra-required: []
1551 extra-allowed: []
1552 Examples
1554 1. With quoted-strings: {quote-type: any, required: true}
1556 the following code snippet would PASS:
1558 foo: "bar"
1560 bar: 'foo'
1561 number: 123
1562 boolean: true
1563 the following code snippet would FAIL:
1565 foo: bar
1567 2. With quoted-strings: {quote-type: single, required:
1569 only-when-needed}
1570 the following code snippet would PASS:
1572 foo: bar
1574 bar: foo
1575 not_number: '123'
1576 not_boolean: 'true'
1577 not_comment: '# comment'
1578 not_list: '[1, 2, 3]'
1579 not_map: '{a: 1, b: 2}'
1580 the following code snippet would FAIL:
1582 foo: 'bar'
1584 3. With quoted-strings: {required: false, extra-required: [^http://,
1586 ^ftp://]}
1587 the following code snippet would PASS:
1589 - localhost
1591 - "localhost"
1592 - "http://localhost"
1593 - "ftp://localhost"
1594 the following code snippet would FAIL:
1596 - http://localhost
1598 - ftp://localhost
1599 4. With quoted-strings: {required: only-when-needed, extra-allowed:
1601 [^http://, ^ftp://], extra-required: [QUOTED]}
1602 the following code snippet would PASS:
1604 - localhost
1606 - "http://localhost"
1607 - "ftp://localhost"
1608 - "this is a string that needs to be QUOTED"
1609 the following code snippet would FAIL:
1611 - "localhost"
1613 - this is a string that needs to be QUOTED
1614 trailing-spaces
1616 Use this rule to forbid trailing spaces at the end of lines.
1617 Examples
1619 1. With trailing-spaces: {}
1621 the following code snippet would PASS:
1623 this document doesn't contain
1625 any trailing
1626 spaces
1627 the following code snippet would FAIL:
1629 this document contains
1631 trailing spaces
1632 on lines 1 and 3
1633 truthy
1635 Use this rule to forbid non-explictly typed truthy values other than
1636 allowed ones (by default: true and false), for example YES or off.
1637 This can be useful to prevent surprises from YAML parsers transforming
1639 [yes, FALSE, Off] into [true, false, false] or {y: 1, yes: 2, on: 3,
1640 true: 4, True: 5} into {y: 1, true: 5}.
1641 Options
1643 · allowed-values defines the list of truthy values which will be
1645 ignored during linting. The default is ['true', 'false'], but can be
1646 changed to any list containing: 'TRUE', 'True', 'true', 'FALSE',
1647 'False', 'false', 'YES', 'Yes', 'yes', 'NO', 'No', 'no', 'ON', 'On',
1648 'on', 'OFF', 'Off', 'off'.
1649 · check-keys disables verification for keys in mappings. By default,
1651 truthy rule applies to both keys and values. Set this option to false
1652 to prevent this.
1653 Default values (when enabled)
1655 rules:
1657 truthy:
1658 allowed-values: ['true', 'false']
1659 check-keys: true
1660 Examples
1662 1. With truthy: {}
1664 the following code snippet would PASS:
1666 boolean: true
1668 object: {"True": 1, 1: "True"}
1670 "yes": 1
1672 "on": 2
1673 "True": 3
1674 explicit:
1676 string1: !!str True
1677 string2: !!str yes
1678 string3: !!str off
1679 encoded: !!binary |
1680 True
1681 OFF
1682 pad== # this decodes as 'N»8Qii'
1683 boolean1: !!bool true
1684 boolean2: !!bool "false"
1685 boolean3: !!bool FALSE
1686 boolean4: !!bool True
1687 boolean5: !!bool off
1688 boolean6: !!bool NO
1689 the following code snippet would FAIL:
1691 object: {True: 1, 1: True}
1693 the following code snippet would FAIL:
1695 yes: 1
1697 on: 2
1698 True: 3
1699 2. With truthy: {allowed-values: ["yes", "no"]}
1701 the following code snippet would PASS:
1703 - yes
1705 - no
1706 - "true"
1707 - 'false'
1708 - foo
1709 - bar
1710 the following code snippet would FAIL:
1712 - true
1714 - false
1715 - on
1716 - off
1717 3. With truthy: {check-keys: false}
1719 the following code snippet would PASS:
1721 yes: 1
1723 on: 2
1724 true: 3
1725 the following code snippet would FAIL:
1727 yes: Yes
1729 on: On
1730 true: True
1731 Disable with comments
1733 Disabling checks for a specific line
1734 To prevent yamllint from reporting problems for a specific line, add a
1735 directive comment (# yamllint disable-line ...) on that line, or on the
1736 line above. For instance:
1737 # The following mapping contains the same key twice,
1739 # but I know what I'm doing:
1740 key: value 1
1741 key: value 2 # yamllint disable-line rule:key-duplicates
1742 - This line is waaaaaaaaaay too long but yamllint will not report anything about it. # yamllint disable-line rule:line-length
1744 This line will be checked by yamllint.
1745 or:
1747 # The following mapping contains the same key twice,
1749 # but I know what I'm doing:
1750 key: value 1
1751 # yamllint disable-line rule:key-duplicates
1752 key: value 2
1753 # yamllint disable-line rule:line-length
1755 - This line is waaaaaaaaaay too long but yamllint will not report anything about it.
1756 This line will be checked by yamllint.
1757 It is possible, although not recommend, to disabled all rules for a
1759 specific line:
1760 # yamllint disable-line
1762 - { all : rules ,are disabled for this line}
1763 If you need to disable multiple rules, it is allowed to chain rules
1765 like this: # yamllint disable-line rule:hyphens rule:commas rule:inden‐
1766 tation.
1767 Disabling checks for all (or part of) the file
1769 To prevent yamllint from reporting problems for the whole file, or for
1770 a block of lines within the file, use # yamllint disable ... and # yam‐
1771 llint enable ... directive comments. For instance:
1772 # yamllint disable rule:colons
1774 - Lorem : ipsum
1775 dolor : sit amet,
1776 consectetur : adipiscing elit
1777 # yamllint enable rule:colons
1778 - rest of the document...
1780 It is possible, although not recommend, to disabled all rules:
1782 # yamllint disable
1784 - Lorem :
1785 ipsum:
1786 dolor : [ sit,amet]
1787 - consectetur : adipiscing elit
1788 # yamllint enable
1789 If you need to disable multiple rules, it is allowed to chain rules
1791 like this: # yamllint disable rule:hyphens rule:commas rule:indenta‐
1792 tion.
1793 Disabling all checks for a file
1795 To prevent yamllint from reporting problems for a specific file, add
1796 the directive comment # yamllint disable-file as the first line of the
1797 file. For instance:
1798 # yamllint disable-file
1800 # The following mapping contains the same key twice, but I know what I'm doing:
1801 key: value 1
1802 key: value 2
1803 - This line is waaaaaaaaaay too long but yamllint will not report anything about it.
1805 This line will be checked by yamllint.
1806 or:
1808 # yamllint disable-file
1810 # This file is not valid YAML because it is a Jinja template
1811 {% if extra_info %}
1812 key1: value1
1813 {% endif %}
1814 key2: value2
1815 Development
1817 yamllint provides both a script and a Python module. The latter can be
1818 used to write your own linting tools.
1819 Basic example of running the linter from Python:
1821 import yamllint
1823 yaml_config = yamllint.config.YamlLintConfig("extends: default")
1825 for p in yamllint.linter.run("example.yaml", yaml_config):
1826 print(p.desc, p.line, p.rule)
1827 class yamllint.linter.LintProblem(line, column, desc='<no descrip‐
1829 tion>', rule=None)
1830 Represents a linting problem found by yamllint.
1831 column Column on which the problem was found (starting at 1)
1833 desc Human-readable description of the problem
1835 line Line on which the problem was found (starting at 1)
1837 rule Identifier of the rule that detected the problem
1839 yamllint.linter.run(input, conf, filepath=None)
1841 Lints a YAML source.
1842 Returns a generator of LintProblem objects.
1844 Parameters
1846 · input -- buffer, string or stream to read from
1848 · conf -- yamllint configuration object
1850 Integration with text editors
1852 Most text editors support syntax checking and highlighting, to visually
1853 report syntax errors and warnings to the user. yamllint can be used to
1854 syntax-check YAML source, but a bit of configuration is required
1855 depending on your favorite text editor.
1856 Vim
1858 Assuming that the ALE plugin is installed, yamllint is supported by
1859 default. It is automatically enabled when editing YAML files.
1860 If you instead use the syntastic plugin, add this to your .vimrc:
1862 let g:syntastic_yaml_checkers = ['yamllint']
1864 Neovim
1866 Assuming that the neomake plugin is installed, yamllint is supported by
1867 default. It is automatically enabled when editing YAML files.
1868 Emacs
1870 If you are flycheck user, you can use flycheck-yamllint integration.
1871 Other text editors
1873 Help wanted!
1874 Your favorite text editor is not listed here? Help us improve by adding
1876 a section (by opening a pull-request or issue on GitHub).
1877 Integration with other software
1879 Integration with pre-commit
1880 You can integrate yamllint in pre-commit tool. Here is an example, to
1881 add in your .pre-commit-config.yaml
1882 ---
1884 # Update the rev variable with the release version that you want, from the yamllint repo
1885 # You can pass your custom .yamllint with args attribute.
1886 - repo: https://github.com/adrienverge/yamllint.git
1887 rev: v1.17.0
1888 hooks:
1889 - id: yamllint
1890 args: [-c=/path/to/.yamllint]
1891 Integration with GitHub Actions
1893 yamllint auto-detects when it's running inside of GitHub
1894 Actions<https://github.com/features/actions> and automatically uses the
1895 suited output format to decorate code with linting errors automati‐
1896 cally. You can also force the GitHub Actions output with yamllint
1897 --format github.
1898 An example workflow using GitHub Actions:
1900 ---
1902 name: yamllint test
1903 on: push
1905 jobs:
1907 test:
1908 runs-on: ubuntu-latest
1909 steps:
1910 - uses: actions/checkout@v2
1911 - name: Set up Python
1913 uses: actions/setup-python@v2
1914 with:
1915 python-version: 3.8
1916 - name: Install yamllint
1918 run: pip install yamllint
1919 - name: Lint YAML files
1921 run: yamllint .
1922 Integration with Arcanist
1924 You can configure yamllint to run on arc lint. Here is an example
1925 .arclint file that makes use of this configuration.
1926 {
1928 "linters": {
1929 "yamllint": {
1930 "type": "script-and-regex",
1931 "script-and-regex.script": "yamllint",
1932 "script-and-regex.regex": "/^(?P<line>\\d+):(?P<offset>\\d+) +(?P<severity>warning|error) +(?P<message>.*) +\\((?P<name>.*)\\)$/m",
1933 "include": "(\\.(yml|yaml)$)"
1934 }
1935 }
1936 }
1937
1939 Adrien Vergé
1940
1942 Copyright 2016, Adrien Vergé
19431.26.0 Jan 29, 2021 YAMLLINT(1)