qmlformat

qmlformat

qmlformat is a tool that automatically formats QML files in accordance with the QML Coding Conventions. More...

Usage:
qmlformat [options] arguments

Options and settings

The following command line options and settings file variables are available:

Command Line OptionSetting NameDefault State/ValueDescription
-h, --helpN/ADisplays help on commandline options.
--help-allN/ADisplays help, including generic Qt options.
-v, --versionN/ADisplays version information.
-V, --verboseN/AVerbose mode. Outputs more detailed information.
--write-defaultsN/AWrites defaults settings to .qmlformat.ini and exits (Warning: This will overwrite any existing settings and comments!)
--ignore-settingsN/AIgnores all settings files and only takes command line options into consideration
-i, --inplaceN/AEdit file in-place instead of outputting to stdout.
-f, --forceN/AContinue even if an error has occurred.
-t, --tabsUseTabsdisabled/falseUse tabs instead of spaces.

In a command line invocation, the behavior can be enabled by passing the flag.

In a settings file, the behavior can be enabled by setting the relevant variable to "true".

-w, --indent-width <width>IndentWidth4How many spaces are used when indenting.
-W, --column-width <width>MaxColumnWidth-1Breaks the line into multiple lines if it exceeds the specified width. Use -1 to disable line wrapping. (default).
-n, --normalizeNormalizeOrderdisabled/falseReorders the attributes of the objects according to the QML Coding Guidelines.

In a command line invocation, the behavior can be enabled by passing the flag.

In a settings file, the behavior can be enabled by setting the relevant variable to "true".

-F, --files <file>N/AFormat all files listed in file, in-place
-l, --newline <newline>NewlineTypenativeOverrides the new line format to use (native, macos, unix, windows).
-S, --sort-importsSortImportsdisabled/falseSort imports alphabetically (Warning: this might change semantics if a given name identifies types in multiple modules!).

In a command line invocation, the behavior can be enabled by passing the flag.

In a settings file, the behavior can be enabled by setting the relevant variable to "true".

--objects-spacingObjectsSpacingdisabled/falseEnsure spaces between objects (only works with normalize option).

In a command line invocation, the behavior can be enabled by passing the flag.

In a settings file, the behavior can be enabled by setting the relevant variable to "true".

--functions-spacingFunctionsSpacingdisabled/falseEnsure spaces between functions (only works with normalize option).

In a command line invocation, the behavior can be enabled by passing the flag.

In a settings file, the behavior can be enabled by setting the relevant variable to "true".

--single-line-empty-objectsSingleLineEmptyObjectsdisabled/falseWrite empty objects on a single line (only works with normalize option).

In a command line invocation, the behavior can be enabled by passing the flag.

In a settings file, the behavior can be enabled by setting the relevant variable to "true".

--semicolon-ruleSemicolonRulealwaysCustomizes the addition of semicolons at the end of JS statements (always, essential).

Note: See Semicolon Rule for more details.

Arguments

Arguments:
filenames

Details

qmlformat is flexible and can be configured according to your needs.

Output

qmlformat writes the formatted version of the file to stdout. If you wish to have your file updated in-place specify the -i flag.

Grouping Properties, Functions, and Signals Together

With -n or --normalize flag, qmlformat groups all properties, functions, and signals together, instead of retaining the order you specified.

Settings File

You can configure qmlformat by including a settings file .qmlformat.ini in your project source or in the parent directories of your project source folder. A default settings file can be obtained by passing the --write-defaults flag. This generates the .qmlformat.ini file in the current working directory.

Warning: --write-defaults will overwrite any existing settings and comments!

Formatting a List of Files

While you can pass a list of files to be formatted as arguments, qmlformat provides -F option to format a set of files stored in a file. In this case, formatting will happen inplace.

// FileList.txt
main.qml
mycomponent.qml

Then, use it like

qmlformat -F FileList.txt

Note: If the file contains an invalid entry, for example, a file path that doesn't exist or a valid file path but the content is an invalid qml document, then qmlformat will error out for that particular entry. It will still format the valid file entries in place.

Warning: If you provide -F option, qmlformat will ignore the positional arguments.

Semicolon Rule

The --semicolon-rule option allows you to customize the addition of semicolons at the end of JS statements. The following values are accepted:

  • always - Always add semicolons (default).
  • essential - Remove semicolons unless omitting them would cause issues.

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.