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 · $XDG_CONFIG_HOME/yamllint/config
121 · ~/.config/yamllint/config
123 Finally if no config file is found, the default configuration is
125 applied.
126 Default configuration
128 Unless told otherwise, yamllint uses its default configuration:
129 ---
131 yaml-files:
133 - '*.yaml'
134 - '*.yml'
135 - '.yamllint'
136 rules:
138 braces: enable
139 brackets: enable
140 colons: enable
141 commas: enable
142 comments:
143 level: warning
144 comments-indentation:
145 level: warning
146 document-end: disable
147 document-start:
148 level: warning
149 empty-lines: enable
150 empty-values: disable
151 hyphens: enable
152 indentation: enable
153 key-duplicates: enable
154 key-ordering: disable
155 line-length: enable
156 new-line-at-end-of-file: enable
157 new-lines: enable
158 octal-values: disable
159 quoted-strings: disable
160 trailing-spaces: enable
161 truthy:
162 level: warning
163 Details on rules can be found on the rules page.
166 There is another pre-defined configuration named relaxed. As its name
168 suggests, it is more tolerant:
169 ---
171 extends: default
173 rules:
175 braces:
176 level: warning
177 max-spaces-inside: 1
178 brackets:
179 level: warning
180 max-spaces-inside: 1
181 colons:
182 level: warning
183 commas:
184 level: warning
185 comments: disable
186 comments-indentation: disable
187 document-start: disable
188 empty-lines:
189 level: warning
190 hyphens:
191 level: warning
192 indentation:
193 level: warning
194 indent-sequences: consistent
195 line-length:
196 level: warning
197 allow-non-breakable-inline-mappings: true
198 truthy: disable
199 It can be chosen using:
202 yamllint -d relaxed file.yml
204 Extending the default configuration
206 When writing a custom configuration file, you don't need to redefine
207 every rule. Just extend the default configuration (or any
208 already-existing configuration file).
209 For instance, if you just want to disable the comments-indentation
211 rule, your file could look like this:
212 # This is my first, very own configuration file for yamllint!
214 # It extends the default conf by adjusting some options.
215 extends: default
217 rules:
219 comments-indentation: disable # don't bother me with this rule
220 Similarly, if you want to set the line-length rule as a warning and be
222 less strict on block sequences indentation:
223 extends: default
225 rules:
227 # 80 chars should be enough, but don't fail if a line is longer
228 line-length:
229 max: 80
230 level: warning
231 # accept both key:
233 # - item
234 #
235 # and key:
236 # - item
237 indentation:
238 indent-sequences: whatever
239 Custom configuration without a config file
241 It is possible -- although not recommended -- to pass custom configura‐
242 tion options to yamllint with the -d (short for --config-data) option.
243 Its content can either be the name of a pre-defined conf (example:
245 default or relaxed) or a serialized YAML object describing the configu‐
246 ration.
247 For instance:
249 yamllint -d "{extends: relaxed, rules: {line-length: {max: 120}}}" file.yaml
251 Errors and warnings
253 Problems detected by yamllint can be raised either as errors or as
254 warnings. The CLI will output them (with different colors when using
255 the colored output format, or auto when run from a terminal).
256 By default the script will exit with a return code 1 only when there is
258 one or more error(s).
259 However if strict mode is enabled with the -s (or --strict) option, the
261 return code will be:
262 · 0 if no errors or warnings occur
264 · 1 if one or more errors occur
266 · 2 if no errors occur, but one or more warnings occur
268 If the script is invoked with the --no-warnings option, it won't output
270 warning level problems, only error level ones.
271 YAML files extensions
273 To configure what yamllint should consider as YAML files, set
274 yaml-files configuration option. The default is:
275 yaml-files:
277 - '*.yaml'
278 - '*.yml'
279 - '.yamllint'
280 The same rules as for ignoring paths apply (.gitignore-style path pat‐
282 tern, see below).
283 Ignoring paths
285 It is possible to exclude specific files or directories, so that the
286 linter doesn't process them.
287 You can either totally ignore files (they won't be looked at):
289 extends: default
291 ignore: |
293 /this/specific/file.yaml
294 all/this/directory/
295 *.template.yaml
296 or ignore paths only for specific rules:
298 extends: default
300 rules:
302 trailing-spaces:
303 ignore: |
304 /this-file-has-trailing-spaces-but-it-is-OK.yaml
305 /generated/*.yaml
306 Note that this .gitignore-style path pattern allows complex path exclu‐
308 sion/inclusion, see the pathspec README file for more details. Here is
309 a more complex example:
310 # For all rules
312 ignore: |
313 *.dont-lint-me.yaml
314 /bin/
315 !/bin/*.lint-me-anyway.yaml
316 extends: default
318 rules:
320 key-duplicates:
321 ignore: |
322 generated
323 *.template.yaml
324 trailing-spaces:
325 ignore: |
326 *.ignore-trailing-spaces.yaml
327 ascii-art/*
328 Rules
330 When linting a document with yamllint, a series of rules (such as
331 line-length, trailing-spaces, etc.) are checked against.
332 A configuration file can be used to enable or disable these rules, to
334 set their level (error or warning), but also to tweak their options.
335 This page describes the rules and their options.
337 List of rules
339 · braces
340 · brackets
342 · colons
344 · commas
346 · comments
348 · comments-indentation
350 · document-end
352 · document-start
354 · empty-lines
356 · empty-values
358 · hyphens
360 · indentation
362 · key-duplicates
364 · key-ordering
366 · line-length
368 · new-line-at-end-of-file
370 · new-lines
372 · octal-values
374 · quoted-strings
376 · trailing-spaces
378 · truthy
380 braces
382 Use this rule to control the number of spaces inside braces ({ and }).
383 Options
385 · min-spaces-inside defines the minimal number of spaces required
387 inside braces.
388 · max-spaces-inside defines the maximal number of spaces allowed inside
390 braces.
391 · min-spaces-inside-empty defines the minimal number of spaces required
393 inside empty braces.
394 · max-spaces-inside-empty defines the maximal number of spaces allowed
396 inside empty braces.
397 Examples
399 1. With braces: {min-spaces-inside: 0, max-spaces-inside: 0}
401 the following code snippet would PASS:
403 object: {key1: 4, key2: 8}
405 the following code snippet would FAIL:
407 object: { key1: 4, key2: 8 }
409 2. With braces: {min-spaces-inside: 1, max-spaces-inside: 3}
411 the following code snippet would PASS:
413 object: { key1: 4, key2: 8 }
415 the following code snippet would PASS:
417 object: { key1: 4, key2: 8 }
419 the following code snippet would FAIL:
421 object: { key1: 4, key2: 8 }
423 the following code snippet would FAIL:
425 object: {key1: 4, key2: 8 }
427 3. With braces: {min-spaces-inside-empty: 0, max-spaces-inside-empty:
429 0}
430 the following code snippet would PASS:
432 object: {}
434 the following code snippet would FAIL:
436 object: { }
438 4. With braces: {min-spaces-inside-empty: 1, max-spaces-inside-empty:
440 -1}
441 the following code snippet would PASS:
443 object: { }
445 the following code snippet would FAIL:
447 object: {}
449 brackets
451 Use this rule to control the number of spaces inside brackets ([ and
452 ]).
453 Options
455 · min-spaces-inside defines the minimal number of spaces required
457 inside brackets.
458 · max-spaces-inside defines the maximal number of spaces allowed inside
460 brackets.
461 · min-spaces-inside-empty defines the minimal number of spaces required
463 inside empty brackets.
464 · max-spaces-inside-empty defines the maximal number of spaces allowed
466 inside empty brackets.
467 Examples
469 1. With brackets: {min-spaces-inside: 0, max-spaces-inside: 0}
471 the following code snippet would PASS:
473 object: [1, 2, abc]
475 the following code snippet would FAIL:
477 object: [ 1, 2, abc ]
479 2. With brackets: {min-spaces-inside: 1, max-spaces-inside: 3}
481 the following code snippet would PASS:
483 object: [ 1, 2, abc ]
485 the following code snippet would PASS:
487 object: [ 1, 2, abc ]
489 the following code snippet would FAIL:
491 object: [ 1, 2, abc ]
493 the following code snippet would FAIL:
495 object: [1, 2, abc ]
497 3. With brackets: {min-spaces-inside-empty: 0, max-spaces-inside-empty:
499 0}
500 the following code snippet would PASS:
502 object: []
504 the following code snippet would FAIL:
506 object: [ ]
508 4. With brackets: {min-spaces-inside-empty: 1, max-spaces-inside-empty:
510 -1}
511 the following code snippet would PASS:
513 object: [ ]
515 the following code snippet would FAIL:
517 object: []
519 colons
521 Use this rule to control the number of spaces before and after colons
522 (:).
523 Options
525 · max-spaces-before defines the maximal number of spaces allowed before
527 colons (use -1 to disable).
528 · max-spaces-after defines the maximal number of spaces allowed after
530 colons (use -1 to disable).
531 Examples
533 1. With colons: {max-spaces-before: 0, max-spaces-after: 1}
535 the following code snippet would PASS:
537 object:
539 - a
540 - b
541 key: value
542 2. With colons: {max-spaces-before: 1}
544 the following code snippet would PASS:
546 object :
548 - a
549 - b
550 the following code snippet would FAIL:
552 object :
554 - a
555 - b
556 3. With colons: {max-spaces-after: 2}
558 the following code snippet would PASS:
560 first: 1
562 second: 2
563 third: 3
564 the following code snippet would FAIL:
566 first: 1
568 2nd: 2
569 third: 3
570 commas
572 Use this rule to control the number of spaces before and after commas
573 (,).
574 Options
576 · max-spaces-before defines the maximal number of spaces allowed before
578 commas (use -1 to disable).
579 · min-spaces-after defines the minimal number of spaces required after
581 commas.
582 · max-spaces-after defines the maximal number of spaces allowed after
584 commas (use -1 to disable).
585 Examples
587 1. With commas: {max-spaces-before: 0}
589 the following code snippet would PASS:
591 strange var:
593 [10, 20, 30, {x: 1, y: 2}]
594 the following code snippet would FAIL:
596 strange var:
598 [10, 20 , 30, {x: 1, y: 2}]
599 2. With commas: {max-spaces-before: 2}
601 the following code snippet would PASS:
603 strange var:
605 [10 , 20 , 30, {x: 1 , y: 2}]
606 3. With commas: {max-spaces-before: -1}
608 the following code snippet would PASS:
610 strange var:
612 [10,
613 20 , 30
614 , {x: 1, y: 2}]
615 4. With commas: {min-spaces-after: 1, max-spaces-after: 1}
617 the following code snippet would PASS:
619 strange var:
621 [10, 20,30, {x: 1, y: 2}]
622 the following code snippet would FAIL:
624 strange var:
626 [10, 20,30, {x: 1, y: 2}]
627 5. With commas: {min-spaces-after: 1, max-spaces-after: 3}
629 the following code snippet would PASS:
631 strange var:
633 [10, 20, 30, {x: 1, y: 2}]
634 6. With commas: {min-spaces-after: 0, max-spaces-after: 1}
636 the following code snippet would PASS:
638 strange var:
640 [10, 20,30, {x: 1, y: 2}]
641 comments
643 Use this rule to control the position and formatting of comments.
644 Options
646 · Use require-starting-space to require a space character right after
648 the #. Set to true to enable, false to disable.
649 · Use ignore-shebangs to ignore a shebang at the beginning of the file
651 when require-starting-space is set.
652 · min-spaces-from-content is used to visually separate inline comments
654 from content. It defines the minimal required number of spaces
655 between a comment and its preceding content.
656 Examples
658 1. With comments: {require-starting-space: true}
660 the following code snippet would PASS:
662 # This sentence
664 # is a block comment
665 the following code snippet would PASS:
667 ##############################
669 ## This is some documentation
670 the following code snippet would FAIL:
672 #This sentence
674 #is a block comment
675 2. With comments: {min-spaces-from-content: 2}
677 the following code snippet would PASS:
679 x = 2 ^ 127 - 1 # Mersenne prime number
681 the following code snippet would FAIL:
683 x = 2 ^ 127 - 1 # Mersenne prime number
685 comments-indentation
687 Use this rule to force comments to be indented like content.
688 Examples
690 1. With comments-indentation: {}
692 the following code snippet would PASS:
694 # Fibonacci
696 [0, 1, 1, 2, 3, 5]
697 the following code snippet would FAIL:
699 # Fibonacci
701 [0, 1, 1, 2, 3, 5]
702 the following code snippet would PASS:
704 list:
706 - 2
707 - 3
708 # - 4
709 - 5
710 the following code snippet would FAIL:
712 list:
714 - 2
715 - 3
716 # - 4
717 - 5
718 the following code snippet would PASS:
720 # This is the first object
722 obj1:
723 - item A
724 # - item B
725 # This is the second object
726 obj2: []
727 the following code snippet would PASS:
729 # This sentence
731 # is a block comment
732 the following code snippet would FAIL:
734 # This sentence
736 # is a block comment
737 document-end
739 Use this rule to require or forbid the use of document end marker
740 (...).
741 Options
743 · Set present to true when the document end marker is required, or to
745 false when it is forbidden.
746 Examples
748 1. With document-end: {present: true}
750 the following code snippet would PASS:
752 ---
754 this:
755 is: [a, document]
756 ...
757 ---
758 - this
759 - is: another one
760 ...
761 the following code snippet would FAIL:
763 ---
765 this:
766 is: [a, document]
767 ---
768 - this
769 - is: another one
770 ...
771 2. With document-end: {present: false}
773 the following code snippet would PASS:
775 ---
777 this:
778 is: [a, document]
779 ---
780 - this
781 - is: another one
782 the following code snippet would FAIL:
784 ---
786 this:
787 is: [a, document]
788 ...
789 ---
790 - this
791 - is: another one
792 document-start
794 Use this rule to require or forbid the use of document start marker
795 (---).
796 Options
798 · Set present to true when the document start marker is required, or to
800 false when it is forbidden.
801 Examples
803 1. With document-start: {present: true}
805 the following code snippet would PASS:
807 ---
809 this:
810 is: [a, document]
811 ---
812 - this
813 - is: another one
814 the following code snippet would FAIL:
816 this:
818 is: [a, document]
819 ---
820 - this
821 - is: another one
822 2. With document-start: {present: false}
824 the following code snippet would PASS:
826 this:
828 is: [a, document]
829 ...
830 the following code snippet would FAIL:
832 ---
834 this:
835 is: [a, document]
836 ...
837 empty-lines
839 Use this rule to set a maximal number of allowed consecutive blank
840 lines.
841 Options
843 · max defines the maximal number of empty lines allowed in the docu‐
845 ment.
846 · max-start defines the maximal number of empty lines allowed at the
848 beginning of the file. This option takes precedence over max.
849 · max-end defines the maximal number of empty lines allowed at the end
851 of the file. This option takes precedence over max.
852 Examples
854 1. With empty-lines: {max: 1}
856 the following code snippet would PASS:
858 - foo:
860 - 1
861 - 2
862 - bar: [3, 4]
864 the following code snippet would FAIL:
866 - foo:
868 - 1
869 - 2
870 - bar: [3, 4]
873 empty-values
875 Use this rule to prevent nodes with empty content, that implicitly
876 result in null values.
877 Options
879 · Use forbid-in-block-mappings to prevent empty values in block map‐
881 pings.
882 · Use forbid-in-flow-mappings to prevent empty values in flow mappings.
884 Examples
886 1. With empty-values: {forbid-in-block-mappings: true}
888 the following code snippets would PASS:
890 some-mapping:
892 sub-element: correctly indented
893 explicitly-null: null
895 the following code snippets would FAIL:
897 some-mapping:
899 sub-element: incorrectly indented
900 implicitly-null:
902 2. With empty-values: {forbid-in-flow-mappings: true}
904 the following code snippet would PASS:
906 {prop: null}
908 {a: 1, b: 2, c: 3}
909 the following code snippets would FAIL:
911 {prop: }
913 {a: 1, b:, c: 3}
915 hyphens
917 Use this rule to control the number of spaces after hyphens (-).
918 Options
920 · max-spaces-after defines the maximal number of spaces allowed after
922 hyphens.
923 Examples
925 1. With hyphens: {max-spaces-after: 1}
927 the following code snippet would PASS:
929 - first list:
931 - a
932 - b
933 - - 1
934 - 2
935 - 3
936 the following code snippet would FAIL:
938 - first list:
940 - a
941 - b
942 the following code snippet would FAIL:
944 - - 1
946 - 2
947 - 3
948 2. With hyphens: {max-spaces-after: 3}
950 the following code snippet would PASS:
952 - key
954 - key2
955 - key42
956 the following code snippet would FAIL:
958 - key
960 - key2
961 - key42
962 indentation
964 Use this rule to control the indentation.
965 Options
967 · spaces defines the indentation width, in spaces. Set either to an
969 integer (e.g. 2 or 4, representing the number of spaces in an inden‐
970 tation level) or to consistent to allow any number, as long as it
971 remains the same within the file.
972 · indent-sequences defines whether block sequences should be indented
974 or not (when in a mapping, this indentation is not mandatory -- some
975 people perceive the - as part of the indentation). Possible values:
976 true, false, whatever and consistent. consistent requires either all
977 block sequences to be indented, or none to be. whatever means either
978 indenting or not indenting individual block sequences is OK.
979 · check-multi-line-strings defines whether to lint indentation in
981 multi-line strings. Set to true to enable, false to disable.
982 Examples
984 1. With indentation: {spaces: 1}
986 the following code snippet would PASS:
988 history:
990 - name: Unix
991 date: 1969
992 - name: Linux
993 date: 1991
994 nest:
995 recurse:
996 - haystack:
997 needle
998 2. With indentation: {spaces: 4}
1000 the following code snippet would PASS:
1002 history:
1004 - name: Unix
1005 date: 1969
1006 - name: Linux
1007 date: 1991
1008 nest:
1009 recurse:
1010 - haystack:
1011 needle
1012 the following code snippet would FAIL:
1014 history:
1016 - name: Unix
1017 date: 1969
1018 - name: Linux
1019 date: 1991
1020 nest:
1021 recurse:
1022 - haystack:
1023 needle
1024 3. With indentation: {spaces: consistent}
1026 the following code snippet would PASS:
1028 history:
1030 - name: Unix
1031 date: 1969
1032 - name: Linux
1033 date: 1991
1034 nest:
1035 recurse:
1036 - haystack:
1037 needle
1038 the following code snippet would FAIL:
1040 some:
1042 Russian:
1043 dolls
1044 4. With indentation: {spaces: 2, indent-sequences: false}
1046 the following code snippet would PASS:
1048 list:
1050 - flying
1051 - spaghetti
1052 - monster
1053 the following code snippet would FAIL:
1055 list:
1057 - flying
1058 - spaghetti
1059 - monster
1060 5. With indentation: {spaces: 2, indent-sequences: whatever}
1062 the following code snippet would PASS:
1064 list:
1066 - flying:
1067 - spaghetti
1068 - monster
1069 - not flying:
1070 - spaghetti
1071 - sauce
1072 6. With indentation: {spaces: 2, indent-sequences: consistent}
1074 the following code snippet would PASS:
1076 - flying:
1078 - spaghetti
1079 - monster
1080 - not flying:
1081 - spaghetti
1082 - sauce
1083 the following code snippet would FAIL:
1085 - flying:
1087 - spaghetti
1088 - monster
1089 - not flying:
1090 - spaghetti
1091 - sauce
1092 7. With indentation: {spaces: 4, check-multi-line-strings: true}
1094 the following code snippet would PASS:
1096 Blaise Pascal:
1098 Je vous écris une longue lettre parce que
1099 je n'ai pas le temps d'en écrire une courte.
1100 the following code snippet would PASS:
1102 Blaise Pascal: Je vous écris une longue lettre parce que
1104 je n'ai pas le temps d'en écrire une courte.
1105 the following code snippet would FAIL:
1107 Blaise Pascal: Je vous écris une longue lettre parce que
1109 je n'ai pas le temps d'en écrire une courte.
1110 the following code snippet would FAIL:
1112 C code:
1114 void main() {
1115 printf("foo");
1116 }
1117 the following code snippet would PASS:
1119 C code:
1121 void main() {
1122 printf("bar");
1123 }
1124 key-duplicates
1126 Use this rule to prevent multiple entries with the same key in map‐
1127 pings.
1128 Examples
1130 1. With key-duplicates: {}
1132 the following code snippet would PASS:
1134 - key 1: v
1136 key 2: val
1137 key 3: value
1138 - {a: 1, b: 2, c: 3}
1139 the following code snippet would FAIL:
1141 - key 1: v
1143 key 2: val
1144 key 1: value
1145 the following code snippet would FAIL:
1147 - {a: 1, b: 2, b: 3}
1149 the following code snippet would FAIL:
1151 duplicated key: 1
1153 "duplicated key": 2
1154 other duplication: 1
1156 ? >-
1157 other
1158 duplication
1159 : 2
1160 key-ordering
1162 Use this rule to enforce alphabetical ordering of keys in mappings. The
1163 sorting order uses the Unicode code point number. As a result, the
1164 ordering is case-sensitive and not accent-friendly (see examples
1165 below).
1166 Examples
1168 1. With key-ordering: {}
1170 the following code snippet would PASS:
1172 - key 1: v
1174 key 2: val
1175 key 3: value
1176 - {a: 1, b: 2, c: 3}
1177 - T-shirt: 1
1178 T-shirts: 2
1179 t-shirt: 3
1180 t-shirts: 4
1181 - hair: true
1182 hais: true
1183 haïr: true
1184 haïssable: true
1185 the following code snippet would FAIL:
1187 - key 2: v
1189 key 1: val
1190 the following code snippet would FAIL:
1192 - {b: 1, a: 2}
1194 the following code snippet would FAIL:
1196 - T-shirt: 1
1198 t-shirt: 2
1199 T-shirts: 3
1200 t-shirts: 4
1201 the following code snippet would FAIL:
1203 - haïr: true
1205 hais: true
1206 line-length
1208 Use this rule to set a limit to lines length.
1209 Note: with Python 2, the line-length rule may not work properly with
1211 unicode characters because of the way strings are represented in bytes.
1212 We recommend running yamllint with Python 3.
1213 Options
1215 · max defines the maximal (inclusive) length of lines.
1217 · allow-non-breakable-words is used to allow non breakable words (with‐
1219 out spaces inside) to overflow the limit. This is useful for long
1220 URLs, for instance. Use true to allow, false to forbid.
1221 · allow-non-breakable-inline-mappings implies allow-non-breakable-words
1223 and extends it to also allow non-breakable words in inline mappings.
1224 Examples
1226 1. With line-length: {max: 70}
1228 the following code snippet would PASS:
1230 long sentence:
1232 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
1233 eiusmod tempor incididunt ut labore et dolore magna aliqua.
1234 the following code snippet would FAIL:
1236 long sentence:
1238 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
1239 tempor incididunt ut labore et dolore magna aliqua.
1240 2. With line-length: {max: 60, allow-non-breakable-words: true}
1242 the following code snippet would PASS:
1244 this:
1246 is:
1247 - a:
1248 http://localhost/very/very/very/very/very/very/very/very/long/url
1249 # this comment is too long,
1251 # but hard to split:
1252 # http://localhost/another/very/very/very/very/very/very/very/very/long/url
1253 the following code snippet would FAIL:
1255 - this line is waaaaaaaaaaaaaay too long but could be easily split...
1257 and the following code snippet would also FAIL:
1259 - foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
1261 3. With line-length: {max: 60, allow-non-breakable-words: true,
1263 allow-non-breakable-inline-mappings: true}
1264 the following code snippet would PASS:
1266 - foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
1268 4. With line-length: {max: 60, allow-non-breakable-words: false}
1270 the following code snippet would FAIL:
1272 this:
1274 is:
1275 - a:
1276 http://localhost/very/very/very/very/very/very/very/very/long/url
1277 new-line-at-end-of-file
1279 Use this rule to require a new line character (\n) at the end of files.
1280 The POSIX standard requires the last line to end with a new line char‐
1282 acter. All UNIX tools expect a new line at the end of files. Most text
1283 editors use this convention too.
1284 new-lines
1286 Use this rule to force the type of new line characters.
1287 Options
1289 · Set type to unix to use UNIX-typed new line characters (\n), or dos
1291 to use DOS-typed new line characters (\r\n).
1292 octal-values
1294 Use this rule to prevent values with octal numbers. In YAML, numbers
1295 that start with 0 are interpreted as octal, but this is not always
1296 wanted. For instance 010 is the city code of Beijing, and should not
1297 be converted to 8.
1298 Examples
1300 1. With octal-values: {forbid-implicit-octal: true}
1302 the following code snippets would PASS:
1304 user:
1306 city-code: '010'
1307 the following code snippets would PASS:
1309 user:
1311 city-code: 010,021
1312 the following code snippets would FAIL:
1314 user:
1316 city-code: 010
1317 2. With octal-values: {forbid-explicit-octal: true}
1319 the following code snippets would PASS:
1321 user:
1323 city-code: '0o10'
1324 the following code snippets would FAIL:
1326 user:
1328 city-code: 0o10
1329 quoted-strings
1331 Use this rule to forbid any string values that are not quoted, or to
1332 prevent quoted strings without needing it. You can also enforce the
1333 type of the quote used.
1334 Options
1336 · quote-type defines allowed quotes: single, double or any (default).
1338 · required defines whether using quotes in string values is required
1340 (true, default) or not (false), or only allowed when really needed
1341 (only-when-needed).
1342 · extra-required is a list of PCRE regexes to force string values to be
1344 quoted, if they match any regex. This option can only be used with
1345 required: false and required: only-when-needed.
1346 · extra-allowed is a list of PCRE regexes to allow quoted string val‐
1348 ues, even if required: only-when-needed is set.
1349 Note: Multi-line strings (with | or >) will not be checked.
1351 Examples
1353 1. With quoted-strings: {quote-type: any, required: true}
1355 the following code snippet would PASS:
1357 foo: "bar"
1359 bar: 'foo'
1360 number: 123
1361 boolean: true
1362 the following code snippet would FAIL:
1364 foo: bar
1366 2. With quoted-strings: {quote-type: single, required:
1368 only-when-needed}
1369 the following code snippet would PASS:
1371 foo: bar
1373 bar: foo
1374 not_number: '123'
1375 not_boolean: 'true'
1376 not_comment: '# comment'
1377 not_list: '[1, 2, 3]'
1378 not_map: '{a: 1, b: 2}'
1379 the following code snippet would FAIL:
1381 foo: 'bar'
1383 3. With quoted-strings: {required: false, extra-required: [^http://,
1385 ^ftp://]}
1386 the following code snippet would PASS:
1388 - localhost
1390 - "localhost"
1391 - "http://localhost"
1392 - "ftp://localhost"
1393 the following code snippet would FAIL:
1395 - http://localhost
1397 - ftp://localhost
1398 4. With quoted-strings: {required: only-when-needed, extra-allowed:
1400 [^http://, ^ftp://], extra-required: [QUOTED]}
1401 the following code snippet would PASS:
1403 - localhost
1405 - "http://localhost"
1406 - "ftp://localhost"
1407 - "this is a string that needs to be QUOTED"
1408 the following code snippet would FAIL:
1410 - "localhost"
1412 - this is a string that needs to be QUOTED
1413 trailing-spaces
1415 Use this rule to forbid trailing spaces at the end of lines.
1416 Examples
1418 1. With trailing-spaces: {}
1420 the following code snippet would PASS:
1422 this document doesn't contain
1424 any trailing
1425 spaces
1426 the following code snippet would FAIL:
1428 this document contains
1430 trailing spaces
1431 on lines 1 and 3
1432 truthy
1434 Use this rule to forbid non-explictly typed truthy values other than
1435 allowed ones (by default: true and false), for example YES or off.
1436 This can be useful to prevent surprises from YAML parsers transforming
1438 [yes, FALSE, Off] into [true, false, false] or {y: 1, yes: 2, on: 3,
1439 true: 4, True: 5} into {y: 1, true: 5}.
1440 Options
1442 · allowed-values defines the list of truthy values which will be
1444 ignored during linting. The default is ['true', 'false'], but can be
1445 changed to any list containing: 'TRUE', 'True', 'true', 'FALSE',
1446 'False', 'false', 'YES', 'Yes', 'yes', 'NO', 'No', 'no', 'ON', 'On',
1447 'on', 'OFF', 'Off', 'off'.
1448 · check-keys disables verification for keys in mappings. By default,
1450 truthy rule applies to both keys and values. Set this option to false
1451 to prevent this.
1452 Examples
1454 1. With truthy: {}
1456 the following code snippet would PASS:
1458 boolean: true
1460 object: {"True": 1, 1: "True"}
1462 "yes": 1
1464 "on": 2
1465 "True": 3
1466 explicit:
1468 string1: !!str True
1469 string2: !!str yes
1470 string3: !!str off
1471 encoded: !!binary |
1472 True
1473 OFF
1474 pad== # this decodes as 'N»8Qii'
1475 boolean1: !!bool true
1476 boolean2: !!bool "false"
1477 boolean3: !!bool FALSE
1478 boolean4: !!bool True
1479 boolean5: !!bool off
1480 boolean6: !!bool NO
1481 the following code snippet would FAIL:
1483 object: {True: 1, 1: True}
1485 the following code snippet would FAIL:
1487 yes: 1
1489 on: 2
1490 True: 3
1491 2. With truthy: {allowed-values: ["yes", "no"]}
1493 the following code snippet would PASS:
1495 - yes
1497 - no
1498 - "true"
1499 - 'false'
1500 - foo
1501 - bar
1502 the following code snippet would FAIL:
1504 - true
1506 - false
1507 - on
1508 - off
1509 3. With truthy: {check-keys: false}
1511 the following code snippet would PASS:
1513 yes: 1
1515 on: 2
1516 true: 3
1517 the following code snippet would FAIL:
1519 yes: Yes
1521 on: On
1522 true: True
1523 Disable with comments
1525 Disabling checks for a specific line
1526 To prevent yamllint from reporting problems for a specific line, add a
1527 directive comment (# yamllint disable-line ...) on that line, or on the
1528 line above. For instance:
1529 # The following mapping contains the same key twice,
1531 # but I know what I'm doing:
1532 key: value 1
1533 key: value 2 # yamllint disable-line rule:key-duplicates
1534 - This line is waaaaaaaaaay too long but yamllint will not report anything about it. # yamllint disable-line rule:line-length
1536 This line will be checked by yamllint.
1537 or:
1539 # The following mapping contains the same key twice,
1541 # but I know what I'm doing:
1542 key: value 1
1543 # yamllint disable-line rule:key-duplicates
1544 key: value 2
1545 # yamllint disable-line rule:line-length
1547 - This line is waaaaaaaaaay too long but yamllint will not report anything about it.
1548 This line will be checked by yamllint.
1549 It is possible, although not recommend, to disabled all rules for a
1551 specific line:
1552 # yamllint disable-line
1554 - { all : rules ,are disabled for this line}
1555 If you need to disable multiple rules, it is allowed to chain rules
1557 like this: # yamllint disable-line rule:hyphens rule:commas rule:inden‐
1558 tation.
1559 Disabling checks for all (or part of) the file
1561 To prevent yamllint from reporting problems for the whole file, or for
1562 a block of lines within the file, use # yamllint disable ... and # yam‐
1563 llint enable ... directive comments. For instance:
1564 # yamllint disable rule:colons
1566 - Lorem : ipsum
1567 dolor : sit amet,
1568 consectetur : adipiscing elit
1569 # yamllint enable rule:colons
1570 - rest of the document...
1572 It is possible, although not recommend, to disabled all rules:
1574 # yamllint disable
1576 - Lorem :
1577 ipsum:
1578 dolor : [ sit,amet]
1579 - consectetur : adipiscing elit
1580 # yamllint enable
1581 If you need to disable multiple rules, it is allowed to chain rules
1583 like this: # yamllint disable rule:hyphens rule:commas rule:indenta‐
1584 tion.
1585 Disabling all checks for a file
1587 To prevent yamllint from reporting problems for a specific file, add
1588 the directive comment # yamllint disable-file as the first line of the
1589 file. For instance:
1590 # yamllint disable-file
1592 # The following mapping contains the same key twice, but I know what I'm doing:
1593 key: value 1
1594 key: value 2
1595 - This line is waaaaaaaaaay too long but yamllint will not report anything about it.
1597 This line will be checked by yamllint.
1598 or:
1600 # yamllint disable-file
1602 # This file is not valid YAML because it is a Jinja template
1603 {% if extra_info %}
1604 key1: value1
1605 {% endif %}
1606 key2: value2
1607 Development
1609 yamllint provides both a script and a Python module. The latter can be
1610 used to write your own linting tools:
1611 class yamllint.linter.LintProblem(line, column, desc='<no descrip‐
1613 tion>', rule=None)
1614 Represents a linting problem found by yamllint.
1615 column = None
1617 Column on which the problem was found (starting at 1)
1618 desc = None
1620 Human-readable description of the problem
1621 line = None
1623 Line on which the problem was found (starting at 1)
1624 rule = None
1626 Identifier of the rule that detected the problem
1627 yamllint.linter.run(input, conf, filepath=None)
1629 Lints a YAML source.
1630 Returns a generator of LintProblem objects.
1632 Parameters
1634 · input -- buffer, string or stream to read from
1636 · conf -- yamllint configuration object
1638 Integration with text editors
1640 Most text editors support syntax checking and highlighting, to visually
1641 report syntax errors and warnings to the user. yamllint can be used to
1642 syntax-check YAML source, but a bit of configuration is required
1643 depending on your favorite text editor.
1644 Vim
1646 Assuming that the ALE plugin is installed, yamllint is supported by
1647 default. It is automatically enabled when editing YAML files.
1648 If you instead use the syntastic plugin, add this to your .vimrc:
1650 let g:syntastic_yaml_checkers = ['yamllint']
1652 Neovim
1654 Assuming that the neomake plugin is installed, yamllint is supported by
1655 default. It is automatically enabled when editing YAML files.
1656 Emacs
1658 If you are flycheck user, you can use flycheck-yamllint integration.
1659 Other text editors
1661 Help wanted!
1662 Your favorite text editor is not listed here? Help us improve by adding
1664 a section (by opening a pull-request or issue on GitHub).
1665 Integration with other software
1667 Integration with pre-commit
1668 You can integrate yamllint in pre-commit tool. Here is an example, to
1669 add in your .pre-commit-config.yaml
1670 ---
1672 # Update the rev variable with the release version that you want, from the yamllint repo
1673 # You can pass your custom .yamllint with args attribute.
1674 - repo: https://github.com/adrienverge/yamllint.git
1675 rev: v1.17.0
1676 hooks:
1677 - id: yamllint
1678 args: [-c=/path/to/.yamllint]
1679
1681 Adrien Vergé
1682
1684 Copyright 2016, Adrien Vergé
16851.23.0 Apr 17, 2020 YAMLLINT(1)