qmllint

qmllint is a tool shipped with Qt, that verifies the syntatic validity of QML files. 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 and result in a non-zero exit code. Minor issues however (such as unused imports) are just informational messages by default and will not 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

Note: In order for qmllint to work properly, it requires type information. That information is provided by QML modules in the import paths. The current directory, as well as the import paths for Qt's built-in types, are used as import paths by default. To add more import paths not included in the default, add them via the -I flag.

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 warnigs are not enabled by default. In order to enable them specify --compiler warning or adjust your settings file accordingly.

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.

Note: As done in the examples above it is preferable to explicitly specify the warning or a list of warnings you want to disable instead of disabling all warnings. This can be done by simply listing warning categories after qmllint disable (the names are the same as the options listed in --help).

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]
AdditionalQmlImportPaths=
DisableDefaultImports=false
OverwriteImportTypes=
ResourcePath=

[Warnings]
BadSignalHandler=warning
Deprecated=warning
ImportFailure=warning
InheritanceCycle=warning
MultilineStrings=info
PropertyAlias=warning
RequiredProperty=warning
TypeError=warning
UnknownProperty=warning
UnqualifiedAccess=warning
UnusedImports=info
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 output JSON via the --json option which will return valid JSON with warning messages, file and line location of warnings, and their severity level. This can be used to more easily integrate qmllint in your pre-commit hooks or CI testing.

See also qmltypes and qtquick-tools-and-utilities.