- Qt 6.12
- Qt Qml
- Qt Qml Tooling
- qmllint
- Qt 6.12.0 Reference Documentation

Deployment ◦ QML Lint Warning and Errors

# qmllint

qmllint is a tool shipped with Qt, that verifies the syntactic validity of QML files. You can integrate qmllint into your build system for ease of use. It also warns about some QML anti-patterns. See {Configuring qmllint warnings} for how to disable a specific warning type.

Note: When using IDE, such as Qt Creator, you don't need to run `qmllint` manually. The IDE uses QML Language Server, that provides real-time linting output and diagnostics as you type.

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.

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.

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 warnings are not enabled by default. In order to enable them, configure qmllint to use the compiler warning category.

### 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.

### Automatically applying fix suggestions

Addressing warnings emitted by qmllint can involve quite some manual editing and validation work. Some of the warnings qmllint emits come with an associated fix suggestion that can be triggered to address the warning automatically. To trigger these fixits, you can:

- Pass `--fix` to qmllint.
- Activate the fixits from your IDE.

Applying all the fixits accross your project at once may be too large of a change. Therefore, it is recommended to divide the work into more manageable parts. You can split the work by linting only a subset of the files, or by running only certain categories.

     qmllint --only-explicit-categories --ignore-settings --fix --unqualified=warning <files>

This will apply the available fixits for unqualified accesses only, by disabling all other warning categories with `--only-explicit-categories` and `--ignore-settings`.

If you are unsure about a change, use `--dry-run` to safely see the result of a run without actually changing the files.

### 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`).

### Configuring qmllint warnings

You can configure the warnings that qmllint emits and their severity level. These levels can be `info`, {warning}, `error`, or `disable`. You can customize the warnings using the `.qmllint.ini` settings file or by passing command line options to qmllint. Command line options override the default and the settings file.

To customize the level of a warning category via the command line, set the corresponding command line option to the desired level.

For example, to disable warnings about deprecations, call qmllint with the `--deprecated=disable` option. And to turn unused imports into an error, pass `--unused-imports=error`.

Customizing warnings in a more permanent way can be done by modifying the settings file. See the upcoming section on Settings files for more details.

### 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`, `error`, 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.

#### Context property settings

Context properties can be defined or ignored by name in their own settings file. Context property settings allow a more fine-grained approach to disabling unqualified access warnings for context property usages, while `.qmllint.ini` only allows to disable all unqualified access warnings, potentially including non-context property related ones.

Context property settings are named `.contextProperties.ini` and should be located inside the source folder of your project. They look like this:

     [General]
     disableUnqualifiedAccess = "myContextProperty1,myContextProperty2"
     warnOnUsage = "myContextProperty3,myContextProperty4,myContextProperty5"
     disableHeuristic = false

To disable qmllint warnings about unqualified access to a context property name, add the context property name to `disableUnqualifiedAccess`. Separate multiple context property names with a comma.

To warn about context property usages, add the context property name to `warnOnUsage`. Separate multiple context property names with a comma.

To control the qmllint heuristic, set `disableHeuristic` to `true` or `false`.

### 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.

See also Type Description Files and Qt Quick Tools and Utilities.

Deployment ◦ QML Lint Warning and Errors