qmlformat

A tool that automatically formats QML files according to the QML coding conventions.

qmlformat is a tool that automatically formats QML files according to the QML Coding Conventions.

Usage:
qmlformat [ options ] arguments

Options and settings

You can configure qmlformat with command-line options. There are two groups of options: those that are directly related to formatting, and those that control the behavior of the tool.

The following options only affect the tool behavior:

Command-line option	Description
-h, --help	Displays help on command-line options.
--help-all	Displays help, including generic Qt options.
-v, --version	Displays version information.
-V, --verbose	Verbose mode. Outputs more detailed information.
--write-defaults	Writes default settings to .qmlformat.ini and exits.
--output-options	Output all available options, their default value, and a hint of values or types.
--ignore-settings	Ignores all settings files and only takes command-line options into consideration.
-i, --inplace	Edit file in-place instead of outputting to stdout.
-f, --force	Continue even if an error occurs.
-F, --files <file>	Format all files listed in file, in-place.

The next group of options controls how files should be formatted, and can also be controlled through a settings file .

For boolean options, pass the flag on the command line or set the variable to true in the settings file to enable the behavior.

Command-line option	Setting name	Default value	Description
-t, --tabs	UseTabs	false	Use tabs instead of spaces.
-w, --indent-width <width>	IndentWidth	4	How many spaces are used when indenting.
-W, --column-width <width>	MaxColumnWidth	-1	Breaks the line into multiple lines if it exceeds the specified width. Use -1 to disable line wrapping (default).
-n, --normalize	NormalizeOrder	false	Reorders and sorts the attributes of objects according to the QML coding guidelines. Incompatible with --group-attributes-together.
-l, --newline <newline>	NewlineType	native	Overrides the new line format to use (native, macos, unix, windows).
-S, --sort-imports	SortImports	false	Sort imports alphabetically (this might change semantics if a given name identifies types in multiple modules).
--objects-spacing	ObjectsSpacing	false	Ensures spaces between objects (only works with normalize or group-attributes-together).
--functions-spacing	FunctionsSpacing	false	Ensures spaces between functions (only works with normalize or group-attributes-together).
--group-attributes-together	GroupAttributesTogether	false	Reorders but does not sort the attributes of objects according to the QML coding guidelines. Incompatible with --normalize.
--single-line-empty-objects	SingleLineEmptyObjects	false	Writes empty objects on a single line (only works with normalize or group-attributes-together).
--semicolon-rule	SemicolonRule	always	Customizes the addition of semicolons at the end of JS statements (always, essential). See Semicolon Rule for more details.

Arguments

Arguments:
filenames

Usage

qmlformat is flexible and can be configured according to your needs. qmlformat should be deployed in a sandbox, container, or other safe environment when running on untrusted code, for example when formatting QML files during testing in a public CI.

Output

qmlformat writes the formatted version of the file to stdout. To have your file updated in-place, specify the -i flag.

Grouping Properties, Functions, and Signals Together

With -n or --normalize flag, qmlformat groups and sorts all properties, functions, and signals by name, instead of retaining the existing order.

For example:

is formatted to:

To group the attributes without sorting by name, use --group-attributes-together instead.

This formats the previous snippet into:

This option takes precedence over --normalize.

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. You can obtain a default settings file by passing the --write-defaults flag. This generates the .qmlformat.ini file in the current working directory.

Warning

--write-defaults overwrites all existing settings and comments.

Formatting a List of Files

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

// FileList.txt
main.qml
mycomponent.qml

To use this list:

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, qmlformat reports an error for that entry and continues to format the remaining valid entries in place.

Warning

If you provide the -F option, qmlformat ignores 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.

Disabling Formatting with Comments

You can temporarily disable qmlformat using special comments.

• // qmlformat off turns off formatting from that line onward.

• // qmlformat on turns on formatting after you turned it off.

This lets you preserve hand-tuned code or complex structures without qmlformat changing their layout. Formatting remains off until the next // qmlformat on comment, or until the end of the file if no re-enable is found.

Keep the following in mind when using formatting directives:

• Directives must be on their own line.

• Nested directives are not supported. Only the first // qmlformat off and the next // qmlformat on are considered. Any additional directives inside a disabled region are ignored.

• Directives are ignored in normalized formatting mode, when sortImports is enabled, or when any option that reorders the original document is used. In these cases, formatting is always applied.