qmllint

qmllint is a tool shipped with Qt, that verifies the syntatic validity of QML files. You can integrate qmllint into your build system for ease of use. It also warns about some QML anti-patterns. If you want to disable a specific warning type, you can find the appropriate flag for doing so by passing --help on the command line.

By default, some issues will result in warnings that will be printed. If there are more warnings than a limit which can be configured with --max-warnings, the exit code will be non-zero. Minor issues however (such as unused imports) are just informational messages by default and will never affect the exit code. qmllint is very configurable and allows for disabling warnings or changing how they are treated. Users may freely turn any issue into a warning, informational message, or disable them outright.

qmllint warns about:

• Unqualified accesses of properties
• Usage of signal handlers without a matching signal
• Usage of with statements in QML
• Issues related to compiling QML code
• Unused imports
• Deprecated components and properties
• And many other things

See QML Lint Warning and Errors on how to fix qmllint warnings and errors.

To get an overview and explanation of all available command line options, run qmllint --help.

Compiler warnings

qmllint can warn you about code that cannot be compiled by qmlsc.

These warnings are not enabled by default. In order to enable them specify --compiler warning or adjust your settings file accordingly.

Using qmllint with CMake

For projects using the qt_add_qml_module() CMake API for creating QML modules, convenience targets such as all_qmllint are created automatically. These run qmllint on all the QML files of a specific module or of the project.

Marking components and properties as deprecated

qmllint allows you to mark both properties and components as deprecated:

 @Deprecated { reason: "Use NewCustomText instead" }
 Text {
     @Deprecated { reason: "Use newProperty instead" }
     property int oldProperty
     property int newProperty
     Component.onCompleted: console.log(oldProperty);  // Warning: XY.qml:8:40: Property "oldProperty" is deprecated (Reason: Use newProperty instead)
 }

Deprecation warnings for components will be shown every time the component is created.

Disabling warnings inline

You may at any point disable warnings temporarily in a file using // qmllint disable.

You can do this at the end of a line when a single line produces warnings:

 Item {
     property string foo
     Item {
         property string bar: foo // qmllint disable unqualified
     }
 }

Alternatively you can disable comments for a block of lines by putting the comment in a line only containing // qmllint disable, ending the block with // qmllint enable:

 Item {
     property string foo
     Item {
         // qmllint disable unqualified
         property string bar: foo
         property string bar2: foo
         // qmllint enable unqualified
     }
 }

qmllint interprets all single line comments starting with qmllint as directives. Thus you may not start a comment that way unless you wish to enable or disable warnings.

Settings

In addition to passing command-line options, you can also configure qmllint via a settings file. The command line --write-defaults will generate one for you.

Setting files are named .qmllint.ini and look like this:

 [General]
 DisableDefaultImports=false
 MaxWarnings=-1

 [Warnings]
 AccessSingletonViaObject=warning
 AliasCycle=warning
 AssignmentInCondition=warning
 AttachedPropertyReuse=disable
 BadSignalHandlerParameters=warning
 Comma=warning
 CompilerWarnings=disable
 ComponentChildrenCount=warning
 ConfusingExpressionStatement=warning
 ConfusingMinuses=warning
 ConfusingPluses=warning
 ContextProperties=warning
 Deprecated=warning
 DuplicateEnumEntries=warning
 DuplicateImport=warning
 DuplicateInlineComponent=warning
 DuplicatePropertyBinding=warning
 DuplicatedName=warning
 EnumEntryMatchesEnum=warning
 EnumsAreNotTypes=warning
 EqualityTypeCoercion=warning
 Eval=warning
 FunctionUsedBeforeDeclaration=disable
 ImportFailure=warning
 IncompatibleType=warning
 InheritanceCycle=warning
 InvalidLintDirective=warning
 LintPluginWarnings=disable
 LiteralConstructor=warning
 MissingEnumEntry=warning
 MissingProperty=warning
 MissingType=warning
 MultilineStrings=info
 NonListProperty=warning
 NonRootEnum=warning
 PreferNonVarProperties=warning
 PrefixedImportType=warning
 PropertyAliasCycles=warning
 QtDesignStudio.FunctionsNotSupportedInQmlUi=warning
 QtDesignStudio.ImperativeCodeNotEditableInVisualDesigner=warning
 QtDesignStudio.InvalidIdeInVisualDesigner=warning
 QtDesignStudio.ReferenceToParentItemNotSupportedByVisualDesigner=warning
 QtDesignStudio.UnsupportedRootTypeInQmlUi=warning
 QtDesignStudio.UnsupportedTypeInQmlUi=warning
 Quick.Anchors=warning
 Quick.AttachedPropertyReuse=disable
 Quick.AttachedPropertyType=warning
 Quick.Color=warning
 Quick.ControlsAttachedPropertyReuse=disable
 Quick.ControlsNativeCustomize=warning
 Quick.LayoutsPositioning=warning
 Quick.PropertyChangesParsed=warning
 Quick.StateNoChildItem=warning
 Quick.UnexpectedVarType=warning
 ReadOnlyProperty=warning
 RedundantOptionalChaining=warning
 RequiredProperty=warning
 RestrictedType=warning
 StalePropertyRead=warning
 TopLevelComponent=warning
 TranslationFunctionMismatch=warning
 UncreatableType=warning
 UnintentionalEmptyBlock=warning
 UnqualifiedAccess=warning
 UnreachableCode=warning
 UnresolvedAlias=warning
 UnresolvedType=warning
 UnterminatedCase=warning
 UnusedImports=info
 UseProperFunction=warning
 VarUsedBeforeDeclaration=warning
 Void=disable
 WithStatement=warning

Warning levels may be set to info, warning or disable just as with command line options.

qmllint will automatically look for a settings file at the location of the qml file that is being linted. It also looks through all parent directories to find this file and automatically applies the settings therein. You can disable this behavior by using --ignore-settings. You may always override these defaults by specifying command line parameters that take precedence over the warning levels in settings.

Scripting

qmllint can write or output JSON via the --json <file> option which will return valid JSON with warning messages, file and line location of warnings, and their severity level. Use the special filename '-' to write to stdout instead of a file. This can be used to more easily integrate qmllint in your pre-commit hooks or CI testing.