- Qt 6.9
- Qt Qml
- Qt Qml Tooling
- qmlformat
- Qt 6.9.3 Reference Documentation

qmllint ◦ qmlls

# qmlformat

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

Usage:
qmlformat [options] arguments

### Options

The following options are available:

Option | Default Value | Description
--- | --- | ---
-h, –help |  | Displays help on commandline 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 defaults settings to .qmlformat.ini and exits (Warning: This will overwrite any existing settings and comments!)
–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 has occurred.
-t, –tabs |  | Use tabs instead of spaces.
-w, –indent-width <width> | 4 | How many spaces are used when indenting.
-W, –column-width <width> | -1 | Breaks the line into multiple lines if it exceeds the specified width. Use -1 to disable line wrapping. (default).
-n, –normalize |  | Reorders the attributes of the objects according to the QML Coding Guidelines.
-F, –files <file> |  | Format all files listed in file, in-place
-l, –newline <newline> |  | Override the new line format to use (native macos unix windows).
–objects-spacing |  | Ensure spaces between objects (only works with normalize option).
–functions-spacing |  | Ensure spaces between functions (only works with normalize option).

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

The following settings are available in the `.qmlformat.ini` file:

Setting | Default Value | Description
--- | --- | ---
UseTabs | false | Uses tabs instead of spaces.
IndentWidth | 4 | How many spaces are used when indenting.
NewlineType | native | Overrides the new line format to use (`native`, `macos`, `unix`, `windows`).
NormalizeOrder | false | Reorders the attributes of the objects according to the QML coding guidelines.
FunctionsSpacing | false | Ensures spaces between functions (only works with normalize option).
ObjectsSpacing | false | Ensures spaces between objects (only works with normalize option).
MaxColumnWidth | -1 | Breaks the line into multiple lines if it exceeds the specified width. Use -1 to disable line wrapping (default).

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