Structuring a Large PyQt Application

I'm building a large GUI application in PySide6 with multiple modules. I have the main layout working, but I'm looking for help with directory structure and software architecture. How should I organize the files and code so it stays manageable as the project grows?

When you're building a small script with a single window, you can get away with putting everything in one file. But as soon as your application starts to grow — multiple screens, different functional modules, shared utilities — that single-file approach becomes painful fast. You lose track of where things are, changes in one place break something elsewhere, and the whole thing becomes hard to maintain.

A well-organized project structure solves this. It keeps your code modular, makes it easier to work on one part without touching the rest, and gives you a clear mental model of how the pieces fit together.

In this article, we'll walk through how to structure a large PyQt6 (or PySide6) application, from directory layout to widget architecture. We'll build a working example that uses a sidebar navigation and stacked pages — a common pattern for applications with multiple modules.

A clean directory layout

When your app has multiple modules or functional areas, it helps to separate things by responsibility. Here's a directory structure that scales well:

myapp/
├── main.py
├── ui/
│   ├── resources/
│   │   ├── icons/
│   │   └── styles/
│   ├── __init__.py
│   ├── main_window.py
│   └── widgets/
│       ├── __init__.py
│       ├── channel_table.py
│       └── status_bar.py
│
└── utils/
        ├── __init__.py
        └── file_io.py

The key idea is to group your UI-related code and assets under a ui/ folder, with any other code or resources kept outside of this ui/ tree. This can be simple utils or other more complicated business logic. Inside the ui/ tree we have the resources, widgets and any other UI-related code.

• main.py — The entry point. This file creates the QApplication and shows the main window. Keep it minimal. If you're new to getting a window on screen, see creating your first window in PyQt6 or PySide6.
• ui/main_window.py — The main window class with the overall layout (sidebar, stacked widget, toolbars, etc.). For guidance on toolbars and menus, see actions, toolbars and menus in PyQt6.
• ui/widgets/ — Reusable custom widgets that might be shared across multiple pages.
• ui/resources/ — Icons, stylesheets, and other non-code assets.
• utils/ — Helper functions and classes that aren't directly tied to the GUI (file I/O, data processing, configuration).

This structure keeps things predictable. When you need to extend or change the application, you know exactly where to look.