qmlimportsort

A tool to organize and sort QML import statements.

Caution

This tool is in early development. Use at your own risk. The CLI is not stable yet — flags and behavior may change in breaking ways until version 1.0.0.

Important

This is a vibe-coded project — most of the code was written collaboratively with an AI assistant.

Note

Comments between two imports are hoisted into a single comment section above the imports — they do not travel with their original import line through sorting. To attach a note to a specific import, put it as a trailing comment on the same line (e.g. import QtQuick // note).

Usage

# Format files or directories in place
qmlimportsort Main.qml
qmlimportsort src/

# Dry run — print paths that would change, exit 1 if any
qmlimportsort --check src/

# Print formatted content to stdout, leave file untouched
qmlimportsort --stdout Main.qml

# Pipe through stdin/stdout
cat Main.qml | qmlimportsort --stdin

# Give your project's modules their own section (repeatable, comma-separated)
qmlimportsort --group io.github.mpvqc. src/

Run qmlimportsort --help for the full flag list.

pre-commit

The tool can run as a pre-commit or prek hook. Add this to your .pre-commit-config.yaml:

repos:
  - repo: "https://github.com/trin94/qml-import-sort"
    rev: "v0.4.0"
    hooks:
      - id: "qml-import-sort"

Go does not need to be installed. Both frameworks download the Go toolchain on demand and build the hook once per rev.

Pass --group prefixes via args:

      - id: "qml-import-sort"
        args: ["--group", "io.github.mpvqc."]

Examples

Imports are grouped into pragmas, Qt, default, custom sections (opt-in), and relative — sorted and de-duplicated within each group, separated by a blank line.

Given this file:

// SPDX-FileCopyrightText: Jane Doe
//
// SPDX-License-Identifier: MIT
import QtQuick.Controls
import "../components"
import MyApp.Views
import org.kde.kirigami as Kirigami
import QtQuick
import Company.Widgets 1.2
import MyApp.Backend
import QtQuick
pragma ComponentBehavior: Bound
import Qt.labs.settings

Item {}

qmlimportsort Main.qml applies the default grouping — everything that is not Qt or relative shares one section:

// SPDX-FileCopyrightText: Jane Doe
//
// SPDX-License-Identifier: MIT

pragma ComponentBehavior: Bound

import Qt.labs.settings
import QtQuick
import QtQuick.Controls

import Company.Widgets 1.2
import MyApp.Backend
import MyApp.Views
import org.kde.kirigami as Kirigami

import "../components"

Item {}

qmlimportsort --group MyApp. Main.qml gives the project's own modules their own section:

// SPDX-FileCopyrightText: Jane Doe
//
// SPDX-License-Identifier: MIT

pragma ComponentBehavior: Bound

import Qt.labs.settings
import QtQuick
import QtQuick.Controls

import Company.Widgets 1.2
import org.kde.kirigami as Kirigami

import MyApp.Backend
import MyApp.Views

import "../components"

Item {}

qmlimportsort --group Company. --group MyApp. Main.qml splits further — one section per namespace, in flag order:

// SPDX-FileCopyrightText: Jane Doe
//
// SPDX-License-Identifier: MIT

pragma ComponentBehavior: Bound

import Qt.labs.settings
import QtQuick
import QtQuick.Controls

import org.kde.kirigami as Kirigami

import Company.Widgets 1.2

import MyApp.Backend
import MyApp.Views

import "../components"

Item {}

Development

Requires Go 1.26+.

just build
just test

License

MIT License