- Qt 6.10
- Qt Qml
- Qt Qml Tooling
- qmlformat
- Qt 6.10.2 Reference Documentation

qmllint ◦ qmlls

# qmlformat

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

Usage:
qmlformat [options] arguments

### Options

qmlformat can be configured via command line options. There are two groups of options: Those which are directly related to formatting, and those which control the behavior of the tool.

The following options only affect the tool behavior:

Command Line Option | 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.
`-F`, `--files <file>` | Format all files listed in file, in-place

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

Option | Default Value | Description
--- | --- | ---
`-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.
`-l`, `--newline <newline>` |  | Override the new line format to use (native macos unix windows).
`-S`, `--sort-imports` |  | Sort imports alphabetically (Warning: this might change semantics if a given name identifies types in multiple modules!).
`--objects-spacing` |  | Ensure spaces between objects (only works with normalize option).
`--functions-spacing` |  | Ensure spaces between functions (only works with normalize option).
`--semicolon-rule` | always | Customize the addition of semicolons at the end of JS statements.

### 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).
SortImports | false | Sorts imports alphabetically. Note: This might change semantics if a given name identifies types in multiple modules.
SemicolonRule | always | Customizes the addition of semicolons at the end of JS statements (`always`, `essential`). Note: See Semicolon Rule for more details.

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