Skip to content

Getting started with EzQt App

This tutorial walks you through installing EzQt App, bootstrapping a project, and launching your first PySide6 application window. By the end you will have a running desktop shell with a sidebar menu and a settings panel.

🔧 Prerequisites

  • Python >= 3.11 (python.org)
  • pip (bundled with Python >= 3.11)
  • A terminal open at your project root

📝 Step 1 — Install EzQt App

uv add ezqt-app

pip install ezqt-app

git clone https://github.com/neuraaak/ezqt-app.git
cd ezqt_app
uv sync

git clone https://github.com/neuraaak/ezqt-app.git
cd ezqt_app
pip install -e ".[dev]"

Verify the installation:

ezqt --version

You should see the package version printed to your terminal.

📝 Step 2 — Bootstrap your project

From your project root, run the init command:

ezqt init

Useful flags

  • --verbose — show every file being generated
  • --force — overwrite existing files
  • --no-main — skip main.py generation

The bootstrap step creates a bin/ directory containing compiled Qt resources, a default theme, and configuration files. You should see a summary of generated files.

Strict config validation

Runtime and save-time configuration parsing now uses strict schema validation. Unknown keys in validated sections can trigger validation errors instead of being silently ignored.

For theme defaults, use settings_panel.theme.default in bin/config/app.config.yaml. app.theme is no longer used.

Alternatively, bootstrap from Python:

from ezqt_app import init

summary = init(mk_theme=True, verbose=True)
print(summary)

📝 Step 3 — Run your first app

Create a main.py at your project root (or use the one generated by ezqt init):

import sys
from ezqt_app import EzApplication, EzQt_App, init

init()                           # (1)!
app = EzApplication(sys.argv)    # (2)!
window = EzQt_App().build()      # (3)!
window.show()
sys.exit(app.exec())
  1. Compiles Qt resources and loads the theme. Must be called before creating widgets.
  2. Creates the Qt application singleton. Manages the event loop and environment.
  3. Constructs the app shell. Call .build() explicitly to enable modular options.

Run it:

python main.py

You should see a desktop window with a collapsible sidebar menu and a settings panel.

📝 Step 4 — Add pages

Register named pages to make the sidebar functional:

import sys
from ezqt_app import EzApplication, EzQt_App, init

init()
app = EzApplication(sys.argv)
window = EzQt_App().build()

home_page = window.add_menu("Home", "home")          # (1)!
settings_page = window.add_menu("Settings", "settings")

window.refresh_theme()   # (2)!
window.show()
sys.exit(app.exec())
  1. add_menu(label, icon_name) registers a page and adds it to the sidebar.
  2. Call refresh_theme() after adding widgets so QSS selectors targeting #objectName are re-evaluated.

✅ What you built

You installed EzQt App, bootstrapped a project with ezqt init, and launched a PySide6 desktop shell with a sidebar navigation, settings panel, and a compiled Qt theme. The application is fully operational and ready for customization.

➡️ Next steps

Common operations

Change language

from ezqt_app.services.translation import change_language_by_code

change_language_by_code("fr")

Toggle theme

window = EzQt_App().build()
window.set_app_theme()

Disable auto-translation

window = EzQt_App().build()
window.enable_auto_translation(False)

Observe theme and translation signals

from ezqt_app.services.translation import get_translation_manager

window = EzQt_App().build()
translation_manager = get_translation_manager()

window.themeChanged.connect(lambda: print("Theme changed"))
translation_manager.languageChanged.connect(
    lambda code: print(f"Language changed -> {code}")
)
translation_manager.translation_started.connect(
    lambda: print("Auto-translation started")
)
translation_manager.translation_finished.connect(
    lambda: print("Auto-translation finished")
)

Custom bin_path

Place generated assets in a directory other than the default bin/:

from ezqt_app import init

init(bin_path="binaries")

The path is resolved relative to project_root (defaults to Path.cwd()).

Service imports

Primary imports are available at the package root:

from ezqt_app import EzApplication, EzQt_App, init

Or from targeted submodules:

from ezqt_app.services.settings import get_settings_service
from ezqt_app.services.translation import get_translation_service

QSS and theming

All .qss files in bin/themes/ are loaded automatically at runtime in alphabetical order:

File Scope
bin/themes/application.qss Application-level styles
bin/themes/extended.qss EzQt extended widgets
bin/themes/global.qss Standard Qt widgets

Troubleshooting

Import error

Make sure you import from ezqt_app (underscore), not ezqt-app (hyphen):

from ezqt_app import EzApplication  # correct

pyside6-rcc not found

pyside6-rcc not found

If pyside6-rcc is missing, init() raises a ResourceCompilationError:

ezqt_app.domain.errors.ResourceCompilationError: pyside6-rcc not found

Ensure PySide6 tools are installed and on PATH:

uv add PySide6
# or verify the executable is available:
uv run python -m PySide6.scripts.pyside6_tool rcc --version

pip install PySide6
# or verify the executable is available:
python -m PySide6.scripts.pyside6_tool rcc --version

In corporate environments, ensure the PySide6_Essentials or PySide6_Addons wheel is also installed alongside the main package.

Missing config or assets after init

Re-run init with the force flag:

ezqt init --force --verbose
CLI command not found

Reinstall in editable mode and verify the entry point:

uv sync
ezqt --version

pip install -e ".[dev]"
ezqt --version
Qt import errors

Verify PySide6 is available in your active environment:

python -c "import PySide6; print(PySide6.__version__)"
PySide6 installation issues

Upgrade pip before installing PySide6:

uv add "PySide6>=6.7.3"

pip install --upgrade pip
pip install "PySide6>=6.7.3"