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 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 or‐
337 der by Unicode code point number, while locales will sort case and ac‐
338 cents 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 • float-values
375 • hyphens
377 • indentation
379 • key-duplicates
381 • key-ordering
383 • line-length
385 • new-line-at-end-of-file
387 • new-lines
389 • octal-values
391 • quoted-strings
393 • trailing-spaces
395 • truthy
397 braces
399 Use this rule to control the use of flow mappings or number of spaces
400 inside braces ({ and }).
401 Options
403 • forbid is used to forbid the use of flow mappings which are denoted
405 by surrounding braces ({ and }). Use true to forbid the use of flow
406 mappings completely. Use non-empty to forbid the use of all flow map‐
407 pings except for empty ones.
408 • min-spaces-inside defines the minimal number of spaces required in‐
410 side braces.
411 • max-spaces-inside defines the maximal number of spaces allowed inside
413 braces.
414 • min-spaces-inside-empty defines the minimal number of spaces required
416 inside empty braces.
417 • max-spaces-inside-empty defines the maximal number of spaces allowed
419 inside empty braces.
420 Default values (when enabled)
422 rules:
424 braces:
425 forbid: false
426 min-spaces-inside: 0
427 max-spaces-inside: 0
428 min-spaces-inside-empty: -1
429 max-spaces-inside-empty: -1
430 Examples
432 1. With braces: {forbid: true}
434 the following code snippet would PASS:
436 object:
438 key1: 4
439 key2: 8
440 the following code snippet would FAIL:
442 object: { key1: 4, key2: 8 }
444 2. With braces: {forbid: non-empty}
446 the following code snippet would PASS:
448 object: {}
450 the following code snippet would FAIL:
452 object: { key1: 4, key2: 8 }
454 3. With braces: {min-spaces-inside: 0, max-spaces-inside: 0}
456 the following code snippet would PASS:
458 object: {key1: 4, key2: 8}
460 the following code snippet would FAIL:
462 object: { key1: 4, key2: 8 }
464 4. With braces: {min-spaces-inside: 1, max-spaces-inside: 3}
466 the following code snippet would PASS:
468 object: { key1: 4, key2: 8 }
470 the following code snippet would PASS:
472 object: { key1: 4, key2: 8 }
474 the following code snippet would FAIL:
476 object: { key1: 4, key2: 8 }
478 the following code snippet would FAIL:
480 object: {key1: 4, key2: 8 }
482 5. With braces: {min-spaces-inside-empty: 0, max-spaces-inside-empty:
484 0}
485 the following code snippet would PASS:
487 object: {}
489 the following code snippet would FAIL:
491 object: { }
493 6. With braces: {min-spaces-inside-empty: 1, max-spaces-inside-empty:
495 -1}
496 the following code snippet would PASS:
498 object: { }
500 the following code snippet would FAIL:
502 object: {}
504 brackets
506 Use this rule to control the use of flow sequences or the number of
507 spaces inside brackets ([ and ]).
508 Options
510 • forbid is used to forbid the use of flow sequences which are denoted
512 by surrounding brackets ([ and ]). Use true to forbid the use of flow
513 sequences completely. Use non-empty to forbid the use of all flow se‐
514 quences except for empty ones.
515 • min-spaces-inside defines the minimal number of spaces required in‐
517 side brackets.
518 • max-spaces-inside defines the maximal number of spaces allowed inside
520 brackets.
521 • min-spaces-inside-empty defines the minimal number of spaces required
523 inside empty brackets.
524 • max-spaces-inside-empty defines the maximal number of spaces allowed
526 inside empty brackets.
527 Default values (when enabled)
529 rules:
531 brackets:
532 forbid: false
533 min-spaces-inside: 0
534 max-spaces-inside: 0
535 min-spaces-inside-empty: -1
536 max-spaces-inside-empty: -1
537 Examples
539 1. With brackets: {forbid: true}
541 the following code snippet would PASS:
543 object:
545 - 1
546 - 2
547 - abc
548 the following code snippet would FAIL:
550 object: [ 1, 2, abc ]
552 2. With brackets: {forbid: non-empty}
554 the following code snippet would PASS:
556 object: []
558 the following code snippet would FAIL:
560 object: [ 1, 2, abc ]
562 3. With brackets: {min-spaces-inside: 0, max-spaces-inside: 0}
564 the following code snippet would PASS:
566 object: [1, 2, abc]
568 the following code snippet would FAIL:
570 object: [ 1, 2, abc ]
572 4. With brackets: {min-spaces-inside: 1, max-spaces-inside: 3}
574 the following code snippet would PASS:
576 object: [ 1, 2, abc ]
578 the following code snippet would PASS:
580 object: [ 1, 2, abc ]
582 the following code snippet would FAIL:
584 object: [ 1, 2, abc ]
586 the following code snippet would FAIL:
588 object: [1, 2, abc ]
590 5. With brackets: {min-spaces-inside-empty: 0, max-spaces-inside-empty:
592 0}
593 the following code snippet would PASS:
595 object: []
597 the following code snippet would FAIL:
599 object: [ ]
601 6. With brackets: {min-spaces-inside-empty: 1, max-spaces-inside-empty:
603 -1}
604 the following code snippet would PASS:
606 object: [ ]
608 the following code snippet would FAIL:
610 object: []
612 colons
614 Use this rule to control the number of spaces before and after colons
615 (:).
616 Options
618 • max-spaces-before defines the maximal number of spaces allowed before
620 colons (use -1 to disable).
621 • max-spaces-after defines the maximal number of spaces allowed after
623 colons (use -1 to disable).
624 Default values (when enabled)
626 rules:
628 colons:
629 max-spaces-before: 0
630 max-spaces-after: 1
631 Examples
633 1. With colons: {max-spaces-before: 0, max-spaces-after: 1}
635 the following code snippet would PASS:
637 object:
639 - a
640 - b
641 key: value
642 2. With colons: {max-spaces-before: 1}
644 the following code snippet would PASS:
646 object :
648 - a
649 - b
650 the following code snippet would FAIL:
652 object :
654 - a
655 - b
656 3. With colons: {max-spaces-after: 2}
658 the following code snippet would PASS:
660 first: 1
662 second: 2
663 third: 3
664 the following code snippet would FAIL:
666 first: 1
668 2nd: 2
669 third: 3
670 commas
672 Use this rule to control the number of spaces before and after commas
673 (,).
674 Options
676 • max-spaces-before defines the maximal number of spaces allowed before
678 commas (use -1 to disable).
679 • min-spaces-after defines the minimal number of spaces required after
681 commas.
682 • max-spaces-after defines the maximal number of spaces allowed after
684 commas (use -1 to disable).
685 Default values (when enabled)
687 rules:
689 commas:
690 max-spaces-before: 0
691 min-spaces-after: 1
692 max-spaces-after: 1
693 Examples
695 1. With commas: {max-spaces-before: 0}
697 the following code snippet would PASS:
699 strange var:
701 [10, 20, 30, {x: 1, y: 2}]
702 the following code snippet would FAIL:
704 strange var:
706 [10, 20 , 30, {x: 1, y: 2}]
707 2. With commas: {max-spaces-before: 2}
709 the following code snippet would PASS:
711 strange var:
713 [10 , 20 , 30, {x: 1 , y: 2}]
714 3. With commas: {max-spaces-before: -1}
716 the following code snippet would PASS:
718 strange var:
720 [10,
721 20 , 30
722 , {x: 1, y: 2}]
723 4. With commas: {min-spaces-after: 1, max-spaces-after: 1}
725 the following code snippet would PASS:
727 strange var:
729 [10, 20, 30, {x: 1, y: 2}]
730 the following code snippet would FAIL:
732 strange var:
734 [10, 20,30, {x: 1, y: 2}]
735 5. With commas: {min-spaces-after: 1, max-spaces-after: 3}
737 the following code snippet would PASS:
739 strange var:
741 [10, 20, 30, {x: 1, y: 2}]
742 6. With commas: {min-spaces-after: 0, max-spaces-after: 1}
744 the following code snippet would PASS:
746 strange var:
748 [10, 20,30, {x: 1, y: 2}]
749 comments
751 Use this rule to control the position and formatting of comments.
752 Options
754 • Use require-starting-space to require a space character right after
756 the #. Set to true to enable, false to disable.
757 • Use ignore-shebangs to ignore a shebang at the beginning of the file
759 when require-starting-space is set.
760 • min-spaces-from-content is used to visually separate inline comments
762 from content. It defines the minimal required number of spaces be‐
763 tween a comment and its preceding content.
764 Default values (when enabled)
766 rules:
768 comments:
769 require-starting-space: true
770 ignore-shebangs: true
771 min-spaces-from-content: 2
772 Examples
774 1. With comments: {require-starting-space: true}
776 the following code snippet would PASS:
778 # This sentence
780 # is a block comment
781 the following code snippet would PASS:
783 ##############################
785 ## This is some documentation
786 the following code snippet would FAIL:
788 #This sentence
790 #is a block comment
791 2. With comments: {min-spaces-from-content: 2}
793 the following code snippet would PASS:
795 x = 2 ^ 127 - 1 # Mersenne prime number
797 the following code snippet would FAIL:
799 x = 2 ^ 127 - 1 # Mersenne prime number
801 comments-indentation
803 Use this rule to force comments to be indented like content.
804 Examples
806 1. With comments-indentation: {}
808 the following code snippet would PASS:
810 # Fibonacci
812 [0, 1, 1, 2, 3, 5]
813 the following code snippet would FAIL:
815 # Fibonacci
817 [0, 1, 1, 2, 3, 5]
818 the following code snippet would PASS:
820 list:
822 - 2
823 - 3
824 # - 4
825 - 5
826 the following code snippet would FAIL:
828 list:
830 - 2
831 - 3
832 # - 4
833 - 5
834 the following code snippet would PASS:
836 # This is the first object
838 obj1:
839 - item A
840 # - item B
841 # This is the second object
842 obj2: []
843 the following code snippet would PASS:
845 # This sentence
847 # is a block comment
848 the following code snippet would FAIL:
850 # This sentence
852 # is a block comment
853 document-end
855 Use this rule to require or forbid the use of document end marker
856 (...).
857 Options
859 • Set present to true when the document end marker is required, or to
861 false when it is forbidden.
862 Default values (when enabled)
864 rules:
866 document-end:
867 present: true
868 Examples
870 1. With document-end: {present: true}
872 the following code snippet would PASS:
874 ---
876 this:
877 is: [a, document]
878 ...
879 ---
880 - this
881 - is: another one
882 ...
883 the following code snippet would FAIL:
885 ---
887 this:
888 is: [a, document]
889 ---
890 - this
891 - is: another one
892 ...
893 2. With document-end: {present: false}
895 the following code snippet would PASS:
897 ---
899 this:
900 is: [a, document]
901 ---
902 - this
903 - is: another one
904 the following code snippet would FAIL:
906 ---
908 this:
909 is: [a, document]
910 ...
911 ---
912 - this
913 - is: another one
914 document-start
916 Use this rule to require or forbid the use of document start marker
917 (---).
918 Options
920 • Set present to true when the document start marker is required, or to
922 false when it is forbidden.
923 Default values (when enabled)
925 rules:
927 document-start:
928 present: true
929 Examples
931 1. With document-start: {present: true}
933 the following code snippet would PASS:
935 ---
937 this:
938 is: [a, document]
939 ---
940 - this
941 - is: another one
942 the following code snippet would FAIL:
944 this:
946 is: [a, document]
947 ---
948 - this
949 - is: another one
950 2. With document-start: {present: false}
952 the following code snippet would PASS:
954 this:
956 is: [a, document]
957 ...
958 the following code snippet would FAIL:
960 ---
962 this:
963 is: [a, document]
964 ...
965 empty-lines
967 Use this rule to set a maximal number of allowed consecutive blank
968 lines.
969 Options
971 • max defines the maximal number of empty lines allowed in the docu‐
973 ment.
974 • max-start defines the maximal number of empty lines allowed at the
976 beginning of the file. This option takes precedence over max.
977 • max-end defines the maximal number of empty lines allowed at the end
979 of the file. This option takes precedence over max.
980 Default values (when enabled)
982 rules:
984 empty-lines:
985 max: 2
986 max-start: 0
987 max-end: 0
988 Examples
990 1. With empty-lines: {max: 1}
992 the following code snippet would PASS:
994 - foo:
996 - 1
997 - 2
998 - bar: [3, 4]
1000 the following code snippet would FAIL:
1002 - foo:
1004 - 1
1005 - 2
1006 - bar: [3, 4]
1009 empty-values
1011 Use this rule to prevent nodes with empty content, that implicitly re‐
1012 sult in null values.
1013 Options
1015 • Use forbid-in-block-mappings to prevent empty values in block map‐
1017 pings.
1018 • Use forbid-in-flow-mappings to prevent empty values in flow mappings.
1020 Default values (when enabled)
1022 rules:
1024 empty-values:
1025 forbid-in-block-mappings: true
1026 forbid-in-flow-mappings: true
1027 Examples
1029 1. With empty-values: {forbid-in-block-mappings: true}
1031 the following code snippets would PASS:
1033 some-mapping:
1035 sub-element: correctly indented
1036 explicitly-null: null
1038 the following code snippets would FAIL:
1040 some-mapping:
1042 sub-element: incorrectly indented
1043 implicitly-null:
1045 2. With empty-values: {forbid-in-flow-mappings: true}
1047 the following code snippet would PASS:
1049 {prop: null}
1051 {a: 1, b: 2, c: 3}
1052 the following code snippets would FAIL:
1054 {prop: }
1056 {a: 1, b:, c: 3}
1058 float-values
1060 Use this rule to limit the permitted values for floating-point numbers.
1061 YAML permits three classes of float expressions: approximation to real
1062 numbers, positive and negative infinity and "not a number".
1063 Options
1065 • Use require-numeral-before-decimal to require floats to start with a
1067 numeral (ex 0.0 instead of .0).
1068 • Use forbid-scientific-notation to forbid scientific notation.
1070 • Use forbid-nan to forbid NaN (not a number) values.
1072 • Use forbid-inf to forbid infinite values.
1074 Default values (when enabled)
1076 rules:
1078 float-values:
1079 forbid-inf: false
1080 forbid-nan: false
1081 forbid-scientific-notation: false
1082 require-numeral-before-decimal: false
1083 Examples
1085 1. With float-values: {require-numeral-before-decimal: true}
1087 the following code snippets would PASS:
1089 anemometer:
1091 angle: 0.0
1092 the following code snippets would FAIL:
1094 anemometer:
1096 angle: .0
1097 2. With float-values: {forbid-scientific-notation: true}
1099 the following code snippets would PASS:
1101 anemometer:
1103 angle: 0.00001
1104 the following code snippets would FAIL:
1106 anemometer:
1108 angle: 10e-6
1109 3. With float-values: {forbid-nan: true}
1111 the following code snippets would FAIL:
1113 anemometer:
1115 angle: .NaN
1116 1. With float-values: {forbid-inf: true}
1118 the following code snippets would FAIL:
1119 anemometer:
1121 angle: .inf
1122 hyphens
1124 Use this rule to control the number of spaces after hyphens (-).
1125 Options
1127 • max-spaces-after defines the maximal number of spaces allowed after
1129 hyphens.
1130 Default values (when enabled)
1132 rules:
1134 hyphens:
1135 max-spaces-after: 1
1136 Examples
1138 1. With hyphens: {max-spaces-after: 1}
1140 the following code snippet would PASS:
1142 - first list:
1144 - a
1145 - b
1146 - - 1
1147 - 2
1148 - 3
1149 the following code snippet would FAIL:
1151 - first list:
1153 - a
1154 - b
1155 the following code snippet would FAIL:
1157 - - 1
1159 - 2
1160 - 3
1161 2. With hyphens: {max-spaces-after: 3}
1163 the following code snippet would PASS:
1165 - key
1167 - key2
1168 - key42
1169 the following code snippet would FAIL:
1171 - key
1173 - key2
1174 - key42
1175 indentation
1177 Use this rule to control the indentation.
1178 Options
1180 • spaces defines the indentation width, in spaces. Set either to an in‐
1182 teger (e.g. 2 or 4, representing the number of spaces in an indenta‐
1183 tion level) or to consistent to allow any number, as long as it re‐
1184 mains the same within the file.
1185 • indent-sequences defines whether block sequences should be indented
1187 or not (when in a mapping, this indentation is not mandatory -- some
1188 people perceive the - as part of the indentation). Possible values:
1189 true, false, whatever and consistent. consistent requires either all
1190 block sequences to be indented, or none to be. whatever means either
1191 indenting or not indenting individual block sequences is OK.
1192 • check-multi-line-strings defines whether to lint indentation in
1194 multi-line strings. Set to true to enable, false to disable.
1195 Default values (when enabled)
1197 rules:
1199 indentation:
1200 spaces: consistent
1201 indent-sequences: true
1202 check-multi-line-strings: false
1203 Examples
1205 1. With indentation: {spaces: 1}
1207 the following code snippet would PASS:
1209 history:
1211 - name: Unix
1212 date: 1969
1213 - name: Linux
1214 date: 1991
1215 nest:
1216 recurse:
1217 - haystack:
1218 needle
1219 2. With indentation: {spaces: 4}
1221 the following code snippet would PASS:
1223 history:
1225 - name: Unix
1226 date: 1969
1227 - name: Linux
1228 date: 1991
1229 nest:
1230 recurse:
1231 - haystack:
1232 needle
1233 the following code snippet would FAIL:
1235 history:
1237 - name: Unix
1238 date: 1969
1239 - name: Linux
1240 date: 1991
1241 nest:
1242 recurse:
1243 - haystack:
1244 needle
1245 3. With indentation: {spaces: consistent}
1247 the following code snippet would PASS:
1249 history:
1251 - name: Unix
1252 date: 1969
1253 - name: Linux
1254 date: 1991
1255 nest:
1256 recurse:
1257 - haystack:
1258 needle
1259 the following code snippet would FAIL:
1261 some:
1263 Russian:
1264 dolls
1265 4. With indentation: {spaces: 2, indent-sequences: false}
1267 the following code snippet would PASS:
1269 list:
1271 - flying
1272 - spaghetti
1273 - monster
1274 the following code snippet would FAIL:
1276 list:
1278 - flying
1279 - spaghetti
1280 - monster
1281 5. With indentation: {spaces: 2, indent-sequences: whatever}
1283 the following code snippet would PASS:
1285 list:
1287 - flying:
1288 - spaghetti
1289 - monster
1290 - not flying:
1291 - spaghetti
1292 - sauce
1293 6. With indentation: {spaces: 2, indent-sequences: consistent}
1295 the following code snippet would PASS:
1297 - flying:
1299 - spaghetti
1300 - monster
1301 - not flying:
1302 - spaghetti
1303 - sauce
1304 the following code snippet would FAIL:
1306 - flying:
1308 - spaghetti
1309 - monster
1310 - not flying:
1311 - spaghetti
1312 - sauce
1313 7. With indentation: {spaces: 4, check-multi-line-strings: true}
1315 the following code snippet would PASS:
1317 Blaise Pascal:
1319 Je vous écris une longue lettre parce que
1320 je n'ai pas le temps d'en écrire une courte.
1321 the following code snippet would PASS:
1323 Blaise Pascal: Je vous écris une longue lettre parce que
1325 je n'ai pas le temps d'en écrire une courte.
1326 the following code snippet would FAIL:
1328 Blaise Pascal: Je vous écris une longue lettre parce que
1330 je n'ai pas le temps d'en écrire une courte.
1331 the following code snippet would FAIL:
1333 C code:
1335 void main() {
1336 printf("foo");
1337 }
1338 the following code snippet would PASS:
1340 C code:
1342 void main() {
1343 printf("bar");
1344 }
1345 key-duplicates
1347 Use this rule to prevent multiple entries with the same key in map‐
1348 pings.
1349 Examples
1351 1. With key-duplicates: {}
1353 the following code snippet would PASS:
1355 - key 1: v
1357 key 2: val
1358 key 3: value
1359 - {a: 1, b: 2, c: 3}
1360 the following code snippet would FAIL:
1362 - key 1: v
1364 key 2: val
1365 key 1: value
1366 the following code snippet would FAIL:
1368 - {a: 1, b: 2, b: 3}
1370 the following code snippet would FAIL:
1372 duplicated key: 1
1374 "duplicated key": 2
1375 other duplication: 1
1377 ? >-
1378 other
1379 duplication
1380 : 2
1381 key-ordering
1383 Use this rule to enforce alphabetical ordering of keys in mappings. The
1384 sorting order uses the Unicode code point number as a default. As a re‐
1385 sult, the ordering is case-sensitive and not accent-friendly (see exam‐
1386 ples below). This can be changed by setting the global locale option.
1387 This allows one to sort case and accents properly.
1388 Examples
1390 1. With key-ordering: {}
1392 the following code snippet would PASS:
1394 - key 1: v
1396 key 2: val
1397 key 3: value
1398 - {a: 1, b: 2, c: 3}
1399 - T-shirt: 1
1400 T-shirts: 2
1401 t-shirt: 3
1402 t-shirts: 4
1403 - hair: true
1404 hais: true
1405 haïr: true
1406 haïssable: true
1407 the following code snippet would FAIL:
1409 - key 2: v
1411 key 1: val
1412 the following code snippet would FAIL:
1414 - {b: 1, a: 2}
1416 the following code snippet would FAIL:
1418 - T-shirt: 1
1420 t-shirt: 2
1421 T-shirts: 3
1422 t-shirts: 4
1423 the following code snippet would FAIL:
1425 - haïr: true
1427 hais: true
1428 2. With global option locale: "en_US.UTF-8" and rule key-ordering: {}
1430 as opposed to before, the following code snippet would now PASS:
1432 - t-shirt: 1
1434 T-shirt: 2
1435 t-shirts: 3
1436 T-shirts: 4
1437 - hair: true
1438 haïr: true
1439 hais: true
1440 haïssable: true
1441 line-length
1443 Use this rule to set a limit to lines length.
1444 Options
1446 • max defines the maximal (inclusive) length of lines.
1448 • allow-non-breakable-words is used to allow non breakable words (with‐
1450 out spaces inside) to overflow the limit. This is useful for long
1451 URLs, for instance. Use true to allow, false to forbid.
1452 • allow-non-breakable-inline-mappings implies allow-non-breakable-words
1454 and extends it to also allow non-breakable words in inline mappings.
1455 Default values (when enabled)
1457 rules:
1459 line-length:
1460 max: 80
1461 allow-non-breakable-words: true
1462 allow-non-breakable-inline-mappings: false
1463 Examples
1465 1. With line-length: {max: 70}
1467 the following code snippet would PASS:
1469 long sentence:
1471 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
1472 eiusmod tempor incididunt ut labore et dolore magna aliqua.
1473 the following code snippet would FAIL:
1475 long sentence:
1477 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
1478 tempor incididunt ut labore et dolore magna aliqua.
1479 2. With line-length: {max: 60, allow-non-breakable-words: true}
1481 the following code snippet would PASS:
1483 this:
1485 is:
1486 - a:
1487 http://localhost/very/very/very/very/very/very/very/very/long/url
1488 # this comment is too long,
1490 # but hard to split:
1491 # http://localhost/another/very/very/very/very/very/very/very/very/long/url
1492 the following code snippet would FAIL:
1494 - this line is waaaaaaaaaaaaaay too long but could be easily split...
1496 and the following code snippet would also FAIL:
1498 - foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
1500 3. With line-length: {max: 60, allow-non-breakable-words: true, al‐
1502 low-non-breakable-inline-mappings: true}
1503 the following code snippet would PASS:
1505 - foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
1507 4. With line-length: {max: 60, allow-non-breakable-words: false}
1509 the following code snippet would FAIL:
1511 this:
1513 is:
1514 - a:
1515 http://localhost/very/very/very/very/very/very/very/very/long/url
1516 new-line-at-end-of-file
1518 Use this rule to require a new line character (\n) at the end of files.
1519 The POSIX standard requires the last line to end with a new line char‐
1521 acter. All UNIX tools expect a new line at the end of files. Most text
1522 editors use this convention too.
1523 new-lines
1525 Use this rule to force the type of new line characters.
1526 Options
1528 • Set type to unix to enforce UNIX-typed new line characters (\n), set
1530 type to dos to enforce DOS-typed new line characters (\r\n), or set
1531 type to platform to infer the type from the system running yamllint
1532 (\n on POSIX / UNIX / Linux / Mac OS systems or \r\n on DOS / Windows
1533 systems).
1534 Default values (when enabled)
1536 rules:
1538 new-lines:
1539 type: unix
1540 octal-values
1542 Use this rule to prevent values with octal numbers. In YAML, numbers
1543 that start with 0 are interpreted as octal, but this is not always
1544 wanted. For instance 010 is the city code of Beijing, and should not
1545 be converted to 8.
1546 Options
1548 • Use forbid-implicit-octal to prevent numbers starting with 0.
1550 • Use forbid-explicit-octal to prevent numbers starting with 0o.
1552 Default values (when enabled)
1554 rules:
1556 octal-values:
1557 forbid-implicit-octal: true
1558 forbid-explicit-octal: true
1559 Examples
1561 1. With octal-values: {forbid-implicit-octal: true}
1563 the following code snippets would PASS:
1565 user:
1567 city-code: '010'
1568 the following code snippets would PASS:
1570 user:
1572 city-code: 010,021
1573 the following code snippets would FAIL:
1575 user:
1577 city-code: 010
1578 2. With octal-values: {forbid-explicit-octal: true}
1580 the following code snippets would PASS:
1582 user:
1584 city-code: '0o10'
1585 the following code snippets would FAIL:
1587 user:
1589 city-code: 0o10
1590 quoted-strings
1592 Use this rule to forbid any string values that are not quoted, or to
1593 prevent quoted strings without needing it. You can also enforce the
1594 type of the quote used.
1595 Options
1597 • quote-type defines allowed quotes: single, double or any (default).
1599 • required defines whether using quotes in string values is required
1601 (true, default) or not (false), or only allowed when really needed
1602 (only-when-needed).
1603 • extra-required is a list of PCRE regexes to force string values to be
1605 quoted, if they match any regex. This option can only be used with
1606 required: false and required: only-when-needed.
1607 • extra-allowed is a list of PCRE regexes to allow quoted string val‐
1609 ues, even if required: only-when-needed is set.
1610 Note: Multi-line strings (with | or >) will not be checked.
1612 Default values (when enabled)
1614 rules:
1616 quoted-strings:
1617 quote-type: any
1618 required: true
1619 extra-required: []
1620 extra-allowed: []
1621 Examples
1623 1. With quoted-strings: {quote-type: any, required: true}
1625 the following code snippet would PASS:
1627 foo: "bar"
1629 bar: 'foo'
1630 number: 123
1631 boolean: true
1632 the following code snippet would FAIL:
1634 foo: bar
1636 2. With quoted-strings: {quote-type: single, required:
1638 only-when-needed}
1639 the following code snippet would PASS:
1641 foo: bar
1643 bar: foo
1644 not_number: '123'
1645 not_boolean: 'true'
1646 not_comment: '# comment'
1647 not_list: '[1, 2, 3]'
1648 not_map: '{a: 1, b: 2}'
1649 the following code snippet would FAIL:
1651 foo: 'bar'
1653 3. With quoted-strings: {required: false, extra-required: [^http://,
1655 ^ftp://]}
1656 the following code snippet would PASS:
1658 - localhost
1660 - "localhost"
1661 - "http://localhost"
1662 - "ftp://localhost"
1663 the following code snippet would FAIL:
1665 - http://localhost
1667 - ftp://localhost
1668 4. With quoted-strings: {required: only-when-needed, extra-allowed:
1670 [^http://, ^ftp://], extra-required: [QUOTED]}
1671 the following code snippet would PASS:
1673 - localhost
1675 - "http://localhost"
1676 - "ftp://localhost"
1677 - "this is a string that needs to be QUOTED"
1678 the following code snippet would FAIL:
1680 - "localhost"
1682 - this is a string that needs to be QUOTED
1683 trailing-spaces
1685 Use this rule to forbid trailing spaces at the end of lines.
1686 Examples
1688 1. With trailing-spaces: {}
1690 the following code snippet would PASS:
1692 this document doesn't contain
1694 any trailing
1695 spaces
1696 the following code snippet would FAIL:
1698 this document contains
1700 trailing spaces
1701 on lines 1 and 3
1702 truthy
1704 Use this rule to forbid non-explictly typed truthy values other than
1705 allowed ones (by default: true and false), for example YES or off.
1706 This can be useful to prevent surprises from YAML parsers transforming
1708 [yes, FALSE, Off] into [true, false, false] or {y: 1, yes: 2, on: 3,
1709 true: 4, True: 5} into {y: 1, true: 5}.
1710 Options
1712 • allowed-values defines the list of truthy values which will be ig‐
1714 nored during linting. The default is ['true', 'false'], but can be
1715 changed to any list containing: 'TRUE', 'True', 'true', 'FALSE',
1716 'False', 'false', 'YES', 'Yes', 'yes', 'NO', 'No', 'no', 'ON', 'On',
1717 'on', 'OFF', 'Off', 'off'.
1718 • check-keys disables verification for keys in mappings. By default,
1720 truthy rule applies to both keys and values. Set this option to false
1721 to prevent this.
1722 Default values (when enabled)
1724 rules:
1726 truthy:
1727 allowed-values: ['true', 'false']
1728 check-keys: true
1729 Examples
1731 1. With truthy: {}
1733 the following code snippet would PASS:
1735 boolean: true
1737 object: {"True": 1, 1: "True"}
1739 "yes": 1
1741 "on": 2
1742 "True": 3
1743 explicit:
1745 string1: !!str True
1746 string2: !!str yes
1747 string3: !!str off
1748 encoded: !!binary |
1749 True
1750 OFF
1751 pad== # this decodes as 'N»8Qii'
1752 boolean1: !!bool true
1753 boolean2: !!bool "false"
1754 boolean3: !!bool FALSE
1755 boolean4: !!bool True
1756 boolean5: !!bool off
1757 boolean6: !!bool NO
1758 the following code snippet would FAIL:
1760 object: {True: 1, 1: True}
1762 the following code snippet would FAIL:
1764 yes: 1
1766 on: 2
1767 True: 3
1768 2. With truthy: {allowed-values: ["yes", "no"]}
1770 the following code snippet would PASS:
1772 - yes
1774 - no
1775 - "true"
1776 - 'false'
1777 - foo
1778 - bar
1779 the following code snippet would FAIL:
1781 - true
1783 - false
1784 - on
1785 - off
1786 3. With truthy: {check-keys: false}
1788 the following code snippet would PASS:
1790 yes: 1
1792 on: 2
1793 true: 3
1794 the following code snippet would FAIL:
1796 yes: Yes
1798 on: On
1799 true: True
1800 Disable with comments
1802 Disabling checks for a specific line
1803 To prevent yamllint from reporting problems for a specific line, add a
1804 directive comment (# yamllint disable-line ...) on that line, or on the
1805 line above. For instance:
1806 # The following mapping contains the same key twice,
1808 # but I know what I'm doing:
1809 key: value 1
1810 key: value 2 # yamllint disable-line rule:key-duplicates
1811 - This line is waaaaaaaaaay too long but yamllint will not report anything about it. # yamllint disable-line rule:line-length
1813 This line will be checked by yamllint.
1814 or:
1816 # The following mapping contains the same key twice,
1818 # but I know what I'm doing:
1819 key: value 1
1820 # yamllint disable-line rule:key-duplicates
1821 key: value 2
1822 # yamllint disable-line rule:line-length
1824 - This line is waaaaaaaaaay too long but yamllint will not report anything about it.
1825 This line will be checked by yamllint.
1826 It is possible, although not recommend, to disabled all rules for a
1828 specific line:
1829 # yamllint disable-line
1831 - { all : rules ,are disabled for this line}
1832 If you need to disable multiple rules, it is allowed to chain rules
1834 like this: # yamllint disable-line rule:hyphens rule:commas rule:inden‐
1835 tation.
1836 Disabling checks for all (or part of) the file
1838 To prevent yamllint from reporting problems for the whole file, or for
1839 a block of lines within the file, use # yamllint disable ... and # yam‐
1840 llint enable ... directive comments. For instance:
1841 # yamllint disable rule:colons
1843 - Lorem : ipsum
1844 dolor : sit amet,
1845 consectetur : adipiscing elit
1846 # yamllint enable rule:colons
1847 - rest of the document...
1849 It is possible, although not recommend, to disabled all rules:
1851 # yamllint disable
1853 - Lorem :
1854 ipsum:
1855 dolor : [ sit,amet]
1856 - consectetur : adipiscing elit
1857 # yamllint enable
1858 If you need to disable multiple rules, it is allowed to chain rules
1860 like this: # yamllint disable rule:hyphens rule:commas rule:indenta‐
1861 tion.
1862 Disabling all checks for a file
1864 To prevent yamllint from reporting problems for a specific file, add
1865 the directive comment # yamllint disable-file as the first line of the
1866 file. For instance:
1867 # yamllint disable-file
1869 # The following mapping contains the same key twice, but I know what I'm doing:
1870 key: value 1
1871 key: value 2
1872 - This line is waaaaaaaaaay too long but yamllint will not report anything about it.
1874 This line will be checked by yamllint.
1875 or:
1877 # yamllint disable-file
1879 # This file is not valid YAML because it is a Jinja template
1880 {% if extra_info %}
1881 key1: value1
1882 {% endif %}
1883 key2: value2
1884 Development
1886 yamllint provides both a script and a Python module. The latter can be
1887 used to write your own linting tools.
1888 Basic example of running the linter from Python:
1890 import yamllint
1892 yaml_config = yamllint.config.YamlLintConfig("extends: default")
1894 for p in yamllint.linter.run("example.yaml", yaml_config):
1895 print(p.desc, p.line, p.rule)
1896 class yamllint.linter.LintProblem(line, column, desc='<no descrip‐
1898 tion>', rule=None)
1899 Represents a linting problem found by yamllint.
1900 column Column on which the problem was found (starting at 1)
1902 desc Human-readable description of the problem
1904 line Line on which the problem was found (starting at 1)
1906 rule Identifier of the rule that detected the problem
1908 yamllint.linter.run(input, conf, filepath=None)
1910 Lints a YAML source.
1911 Returns a generator of LintProblem objects.
1913 Parameters
1915 • input -- buffer, string or stream to read from
1917 • conf -- yamllint configuration object
1919 Integration with text editors
1921 Most text editors support syntax checking and highlighting, to visually
1922 report syntax errors and warnings to the user. yamllint can be used to
1923 syntax-check YAML source, but a bit of configuration is required de‐
1924 pending on your favorite text editor.
1925 Vim
1927 Assuming that the ALE plugin is installed, yamllint is supported by de‐
1928 fault. It is automatically enabled when editing YAML files.
1929 If you instead use the syntastic plugin, add this to your .vimrc:
1931 let g:syntastic_yaml_checkers = ['yamllint']
1933 Neovim
1935 Assuming that the neomake plugin is installed, yamllint is supported by
1936 default. It is automatically enabled when editing YAML files.
1937 Emacs
1939 If you are flycheck user, you can use flycheck-yamllint integration.
1940 Visual Studio Code
1942 https://marketplace.visualstudio.com/items?itemName=fnando.linter
1943 IntelliJ
1945 https://plugins.jetbrains.com/plugin/15349-yamllint
1946 Other text editors
1948 Help wanted!
1949 Your favorite text editor is not listed here? Help us improve by adding
1951 a section (by opening a pull-request or issue on GitHub).
1952 Integration with other software
1954 Integration with pre-commit
1955 You can integrate yamllint in pre-commit tool. Here is an example, to
1956 add in your .pre-commit-config.yaml
1957 ---
1959 # Update the rev variable with the release version that you want, from the yamllint repo
1960 # You can pass your custom .yamllint with args attribute.
1961 - repo: https://github.com/adrienverge/yamllint.git
1962 rev: v1.17.0
1963 hooks:
1964 - id: yamllint
1965 args: [-c=/path/to/.yamllint]
1966 Integration with GitHub Actions
1968 yamllint auto-detects when it's running inside of GitHub Actions and
1969 automatically uses the suited output format to decorate code with lint‐
1970 ing errors. You can also force the GitHub Actions output with yamllint
1971 --format github.
1972 An example workflow using GitHub Actions:
1974 ---
1976 name: yamllint test
1977 on: push
1979 jobs:
1981 test:
1982 runs-on: ubuntu-latest
1983 steps:
1984 - uses: actions/checkout@v2
1985 - name: Set up Python
1987 uses: actions/setup-python@v2
1988 with:
1989 python-version: 3.8
1990 - name: Install yamllint
1992 run: pip install yamllint
1993 - name: Lint YAML files
1995 run: yamllint .
1996 Integration with Arcanist
1998 You can configure yamllint to run on arc lint. Here is an example .ar‐
1999 clint file that makes use of this configuration.
2000 {
2002 "linters": {
2003 "yamllint": {
2004 "type": "script-and-regex",
2005 "script-and-regex.script": "yamllint",
2006 "script-and-regex.regex": "/^(?P<line>\\d+):(?P<offset>\\d+) +(?P<severity>warning|error) +(?P<message>.*) +\\((?P<name>.*)\\)$/m",
2007 "include": "(\\.(yml|yaml)$)"
2008 }
2009 }
2010 }
2011
2013 Adrien Vergé
2014
2016 2022, Adrien Vergé
20171.27.1 Jul 08, 2022 YAMLLINT(1)