We're excited to announce the release of Qt Custom Widgets version 2.0.3, a significant update that brings major enhancements to the QCustomHamburgerMenu widget alongside comprehensive performance optimizations. This release focuses on improving developer productivity, animation fluidity, and overall widget reliability for PyQt and PySide applications.
We're excited to announce the release of QT-PyQt-PySide-Custom-Widgets version 2.0.2! This update brings significant improvements to the project creation experience and introduces powerful automation features that will streamline your Qt development workflow.
The project creation wizard has been completely overhauled with:
Never manually convert UI files again! The new file monitoring feature:
The command-line interface now includes:
# Start UI file monitoring
Custom_Widgets --monitor-ui ui --qt-library PySide6
# Launch Qt Designer with plugins
Custom_Widgets --start-designer --plugins
# Register custom widgets
Custom_Widgets --register-widgets
# Convert UI files manually
Custom_Widgets --convert-ui ui/main_window.ui
New Installation:
pip install QT-PyQt-PySide-Custom-Widgets
Update Existing Installation:
pip install --upgrade QT-PyQt-PySide-Custom-Widgets
Found an issue or have suggestions? Please report them on our GitHub Issues page: https://github.com/KhamisiKibet/Qt-PyQt-PySide-Custom-Widgets/issues
Thank you to all our contributors and the amazing community for your feedback and support! Your input helps make this library better with every release.
Happy coding!
Follow us for more updates:
#Python #Qt #PySide #PyQt #GUI #Development #OpenSource #CustomWidgets #Release
First, ensure you have Python 3.7 or higher installed:
Windows:
# Download from python.org or use winget
winget install Python.Python.3.11
macOS:
# Using Homebrew
brew install python
Linux (Ubuntu/Debian):
sudo apt update
sudo apt install python3 python3-pip python3-venv
Always use a virtual environment to manage dependencies:
# Create project directory
mkdir my_qt_project
cd my_qt_project
# Create virtual environment
python -m venv venv
# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
Your terminal should now show (venv) indicating the virtual environment is active.
Important: Make sure your virtual environment is activated (you see (venv) in your terminal).
Choose and install one of these Qt bindings:
pip install PySide6
pip install PyQt6
pip install PySide2
pip install PyQt5
Note: For this tutorial, we'll use PySide6 as it's the most modern and freely available.
Install the custom widgets package (make sure venv is active):
pip install QT-PyQt-PySide-Custom-Widgets
Verify installation:
python -c "import Custom_Widgets; print('Custom Widgets installed successfully!')"
Important: Run this command from INSIDE your activated virtual environment folder:
# You should be in your project directory with venv activated
# Your terminal should show: (venv) path/to/your/project$
# Run project creator FROM INSIDE THE VENV FOLDER
Custom_Widgets --create-project
What happens when you run the project creator:
The project creator will guide you through:
my_qt_project/ # Your project folder
├── venv/ # Virtual environment (already created)
│ ├── bin/ # or Scripts/ on Windows
│ ├── lib/
│ └── pyvenv.cfg
└── (project files will be created here by the creator)
Common Mistake to Avoid:
venv foldervenv is locatedIf you prefer manual setup, create this structure in your project root:
my_qt_project/
├── venv/ # Virtual environment
├── main.py # Main application file
├── ui/ # UI files directory
│ └── main_window.ui
├── json-styles/ # Theme configuration
│ └── style.json
├── requirements.txt # Dependencies
└── README.md # Documentation
After running the project creator from inside your venv folder, you'll have:
my_qt_project/
├── venv/ # Virtual environment
├── main.py # Main application file
├── ui/ # UI files directory
│ └── QCustomQMainWindow.ui
├── json-styles/ # Theme configuration
│ └── style.json
├── requirements.txt # Dependencies
└── README.md # Documentation
Before designing your interface, register the custom widgets (from your activated venv):
# Register widgets with Qt Designer
Custom_Widgets --register-widgets
Expected Output:
Registering QCustomQMainWindow...
Registering QCustomSidebar...
Registering QCustomProgressBar...
... (all widgets registered successfully)
Start Qt Designer with the custom widgets loaded (from activated venv):
# Launch Qt Designer with custom widgets
Custom_Widgets --start-designer --plugins
Alternative methods:
# If the above doesn't work, try:
designer
# or
pyside6-designer
# or
qt5-designer
When Qt Designer opens, look for these widget groups in the widget box:
MainWindow Section:
QCustomQMainWindow - Enhanced main window with theme supportSidebar Section:
QCustomSidebar - Customizable sidebar navigationQCustomSidebarButton - Buttons for sidebarQCustomSidebarLabel - Labels for sidebarProgressbars Section:
QCustomRoundProgressBar - Circular progress indicatorAnalogGaugeWidget - Analog gauge displayComponent Container Section:
QCustomComponent - Container for organizing widgetsQCustomComponentContainer - Main container componentStart with QCustomQMainWindow:
QCustomQMainWindow from the widget box to the formAdd a Sidebar:
QCustomSidebar to the left side of your main windowQCustomSidebarButton widgets inside the sidebarAdd Content Area:
QCustomComponent as content containersQCustomQStackedWidget to manage multiple pagesStyle Your Interface:
Save Your Design:
main_window.ui in the ui/ folder.ui extensionKeep this running while you design (from activated venv):
# Monitor UI folder for changes
Custom_Widgets --monitor-ui ui --qt-library PySide6
What this does:
ui/ folder for any changes.ui files to Python when you saveIf you prefer manual conversion:
# Convert specific file
Custom_Widgets --convert-ui ui/main_window.ui --qt-library PySide6
# Convert all files in folder
Custom_Widgets --convert-ui ui --qt-library PySide6
Edit the json-styles/style.json file to customize your app's appearance:
{
"QtBinding": "PySide6",
"QMainWindow": {
"title": "My Awesome App"
},
"QSettings": {
"AppSettings": {
"OrginizationName": "My Company",
"ApplicationName": "My App",
"OrginizationDormain": "myapp.org"
},
"ThemeSettings": {
"QtDesignerIconsColor": "#ffffff",
"CustomThemes": [
{
"Background-color": "#2b2b2b",
"Text-color": "#ffffff",
"Accent-color": "#0078d4",
"Icons-color": "#ffffff",
"Theme-name": "Default Dark",
"Default-Theme": true
}
]
}
}
}
Key Configuration Options:
Background-color: Main app backgroundText-color: Default text colorAccent-color: Primary accent color for buttons, highlightsIcons-color: Color of all icons in the appExecute your application (from activated venv):
python main.py
Your custom-styled application should launch with:
source venv/bin/activate (or venv\Scripts\activate on Windows).ui file (auto-conversion happens if monitoring)# Start monitoring when beginning work
Custom_Widgets --monitor-ui ui --qt-library PySide6
# Launch designer when needed
Custom_Widgets --start-designer --plugins
# Run your app
python main.py
# 1. Start fresh each day
cd my_qt_project
source venv/bin/activate # or venv\Scripts\activate on Windows
# 2. Start file monitoring (keep this terminal open)
Custom_Widgets --monitor-ui ui --qt-library PySide6
# 3. In another terminal, launch designer
cd my_qt_project
source venv/bin/activate
Custom_Widgets --start-designer --plugins
# 4. When ready to test
python main.py
Add additional themes to your style.json:
"CustomThemes": [
{
"Background-color": "#2b2b2b",
"Text-color": "#ffffff",
"Accent-color": "#0078d4",
"Icons-color": "#ffffff",
"Theme-name": "Dark Blue",
"Default-Theme": true
},
{
"Background-color": "#f0f0f0",
"Text-color": "#000000",
"Accent-color": "#e74c3c",
"Icons-color": "#000000",
"Theme-name": "Light Red",
"Default-Theme": false
}
]
Each custom widget has specific properties you can set in Qt Designer:
backgroundColor, activeColor, iconSizeprogressColor, background_color, text_colorenableCustomTitleBar, enableGradient# Check if venv is activated
which python # Should point to venv directory
# If not activated:
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows
# Re-register widgets (from activated venv)
Custom_Widgets --register-widgets
# Restart Qt Designer
Custom_Widgets --start-designer --plugins
# Check if monitoring is running (from activated venv)
Custom_Widgets --monitor-ui ui --qt-library PySide6
# Manual conversion (from activated venv)
Custom_Widgets --convert-ui ui/main_window.ui --qt-library PySide6
# Ensure package is installed in venv
pip install QT-PyQt-PySide-Custom-Widgets
# Check virtual environment is activated
which python # Should point to venv directory
# Make sure you're in the correct directory
pwd # Should show your project folder, not inside venv
# Check folder contents
ls -la # Should show venv folder and your project files
# If you accidentally ran creator in wrong location:
# Delete the generated files and run again from correct location
Now that you have a basic application running:
Congratulations! You've successfully set up a Qt application with custom widgets using proper virtual environment practices. The automated workflow will make your development process much smoother as you continue building your application.
Key Takeaway: Always remember to activate your virtual environment before running any Custom_Widgets commands or your Python application!
In this guide, we'll walk through creating professional Qt Dark and Light themes for your custom widgets applications. These themes follow Qt's design language while providing modern, visually appealing interfaces.
#1e1e1e (Dark gray)#e0e0e0 (Light gray)#41cd52 (Qt green)#41cd52 (Qt green)#2c2c2c (Slightly lighter dark gray)#111111 (Near black)#ffffff (Pure white)#1e1e1e (Dark gray)#41cd52 (Qt green)#41cd52 (Qt green)#f8f8f8 (Off-white)#e5e5e5 (Light gray)Here's how to implement both themes in your style.json:
{
"QSettings": [
{
"ThemeSettings": {
"QtDesignerIconsColor": "#41CD52",
"CustomThemes": [
{
"Theme-name": "Qt-Dark-Theme",
"Background-color": "#1e1e1e",
"Text-color": "#e0e0e0",
"Accent-color": "#41cd52",
"Icons-color": "#41cd52",
"Default-Theme": true,
"Create-icons": true,
"Other-variables": {
"CARD_RADIUS": "12px",
"FOOTER_BG": "#111111",
"NAV_BG": "#1e1e1e",
"CARD_BG": "#2c2c2c",
"BORDER_COLOR": "rgba(65, 205, 82, 0.3)",
"HOVER_GLOW": "0 12px 32px rgba(65, 205, 82, 0.45)",
"GRADIENT": "linear-gradient(135deg, #41cd52, #2fa440)"
}
},
{
"Theme-name": "Qt-Light-Theme",
"Background-color": "#ffffff",
"Text-color": "#1e1e1e",
"Accent-color": "#41cd52",
"Icons-color": "#41cd52",
"Default-Theme": false,
"Create-icons": true,
"Other-variables": {
"CARD_RADIUS": "12px",
"FOOTER_BG": "#e5e5e5",
"NAV_BG": "#f5f5f5",
"CARD_BG": "#f8f8f8",
"BORDER_COLOR": "rgba(65, 205, 82, 0.2)",
"HOVER_GLOW": "0 12px 32px rgba(65, 205, 82, 0.25)",
"GRADIENT": "linear-gradient(135deg, #41cd52, #2fa440)"
}
}
]
}
}
]
}
#1e1e1e) and text (#e0e0e0)#ffffff) and text (#1e1e1e)#41cd52) across both themesBackground-color: Main application backgroundText-color: Primary text color for readabilityAccent-color: Primary brand color for interactive elementsIcons-color: Color for all icon assetsCARD_RADIUS: Border radius for cards and containersFOOTER_BG: Background color for footer areasNAV_BG: Background for navigation elementsCARD_BG: Background for card componentsBORDER_COLOR: Border colors with theme-appropriate opacityHOVER_GLOW: Shadow effects for interactive statesGRADIENT: CSS gradients for visual enhancements"Default-Theme": true
Set this to true for your preferred default theme. The other theme should have false.
"Create-icons": true
This ensures icons are automatically generated in your theme colors.
Notice how border colors use rgba with different opacity:
rgba(65, 205, 82, 0.3) (more visible)rgba(65, 205, 82, 0.2) (more subtle)0.45 opacity)0.25 opacity)To implement theme switching in your application:
"Default-Theme": trueTo use a different accent color, simply replace all instances of #41cd52 with your preferred color:
"Accent-color": "#0078d4",
"Icons-color": "#0078d4",
"QtDesignerIconsColor": "#0078d4"
For higher contrast in the dark theme:
"Background-color": "#121212",
"Text-color": "#ffffff"
For softer or sharper corners:
"CARD_RADIUS": "8px" // Softer
"CARD_RADIUS": "16px" // Rounder
These Qt Dark and Light themes provide a solid foundation for creating professional applications with custom widgets. The color schemes are carefully chosen to be both aesthetically pleasing and functionally effective, following modern design principles while staying true to Qt's visual identity.
Remember to test your themes in different lighting conditions and consider user preferences when deciding which theme to set as default. The flexibility of this system allows you to easily create additional theme variations or customize the existing ones to match your specific application needs.
For more advanced theming options, refer to the Custom Widgets documentation on GitHub and explore additional styling variables available for specific widget types.
This guide explains how to use the auto-generated theme variables in your QSS/SCSS files to create dynamic, theme-aware styles for your Qt applications.
When you define themes in your style.json file, the Custom Widgets system automatically generates SCSS variables that you can use throughout your stylesheets. These variables are created based on your theme colors and custom variables.
The system generates a comprehensive color palette from your base theme colors:
$COLOR_BACKGROUND_1 through $COLOR_BACKGROUND_6 (6 shades from light to dark)$COLOR_TEXT_1 through $COLOR_TEXT_4 (4 shades from light to dark)$COLOR_ACCENT_1 through $COLOR_ACCENT_4 (4 shades from light to dark)$CB1_R, $CB1_G, $CB1_B for background colors)$BORDER_1, $BORDER_2, $BORDER_3)$BORDER_SELECTION_1, etc.)$SIZE_BORDER_RADIUS$OPACITY_TOOLTIP$PATH_RESOURCES, $RELATIVE_FOLDERVariables defined in your JSON theme under "Other-variables" are also available:
"Other-variables": {
"CARD_RADIUS": "12px",
"FOOTER_BG": "#0f0f0f",
"NAV_BG": "#1e1e1e"
}
QWidget {
background-color: $COLOR_BACKGROUND_1;
color: $COLOR_TEXT_1;
}
QPushButton {
background-color: $COLOR_ACCENT_1;
color: $COLOR_TEXT_1;
border-radius: $SIZE_BORDER_RADIUS;
border: $BORDER_1;
}
Use the RGB variables to create dynamic gradients:
QFrame#gradientFrame {
background: qlineargradient(
x1:0, y1:0, x2:1, y2:1,
stop:0 rgba($CB1_R, $CB1_G, $CB1_B, 255),
stop:1 rgba($CB3_R, $CB3_G, $CB3_B, 255)
);
}
// Cards with custom radius
QFrame#card {
background-color: $COLOR_BACKGROUND_2;
border-radius: $CARD_RADIUS;
border: $BORDER_2;
}
// Navigation elements
QWidget#navigation {
background-color: $NAV_BG;
}
// Footer styling
QWidget#footer {
background-color: $FOOTER_BG;
}
For more complex components, you can create custom variables:
// Define custom gradients using theme variables
$MY_GRADIENT: qlineargradient(
x1:0, y1:0, x2:1, y2:0.869,
stop:0 $COLOR_BACKGROUND_1,
stop:1 $COLOR_BACKGROUND_3
);
QMainWindow#customWindow {
background: $MY_GRADIENT;
QPushButton {
background-color: $COLOR_ACCENT_2;
&:hover {
background-color: $COLOR_ACCENT_1;
}
}
}
QLineEdit, QComboBox {
background-color: $COLOR_BACKGROUND_2;
border: 2px solid $COLOR_BACKGROUND_4;
border-radius: 8px;
padding: 8px;
&:focus {
border-color: $COLOR_ACCENT_1;
}
}
// Use accent colors for status indicators
.status-success {
color: $COLOR_ACCENT_1;
border: 1px solid $COLOR_ACCENT_1;
}
.status-warning {
color: $COLOR_ACCENT_2;
border: 1px solid $COLOR_ACCENT_2;
}
.status-error {
color: $COLOR_ACCENT_3;
border: 1px solid $COLOR_ACCENT_3;
}
Create meaningful variable names for your custom styles:
$CARD_BACKGROUND: $COLOR_BACKGROUND_2;
$HEADER_TEXT: $COLOR_TEXT_1;
$BUTTON_PRIMARY: $COLOR_ACCENT_1;
$COLOR_BACKGROUND_1 for main backgrounds$COLOR_BACKGROUND_2 for cards and panels$COLOR_BACKGROUND_3 for nested elementsFor complex styles, create SCSS mixins:
@mixin card-style {
background-color: $COLOR_BACKGROUND_2;
border-radius: $CARD_RADIUS;
border: $BORDER_2;
padding: 16px;
}
.my-card {
@include card-style;
}
Create semi-transparent overlays using RGB variables:
.overlay {
background-color: rgba($CB1_R, $CB1_G, $CB1_B, 0.8);
}
Create animations that work with any theme:
QPushButton {
background-color: $COLOR_ACCENT_2;
transition: background-color 0.3s ease;
&:hover {
background-color: $COLOR_ACCENT_1;
}
}
When users switch themes, all variables are automatically updated, and your styles will reflect the new color scheme without any code changes.
// Dashboard card component
#DashboardCard {
background: qlineargradient(
x1:0, y1:0, x2:1, y2:1,
stop:0 $COLOR_BACKGROUND_2,
stop:1 $COLOR_BACKGROUND_3
);
border-radius: $CARD_RADIUS;
border: $BORDER_2;
QLabel#title {
color: $COLOR_TEXT_1;
font-size: 16px;
font-weight: bold;
}
QLabel#value {
color: $COLOR_ACCENT_1;
font-size: 24px;
font-weight: bold;
}
QPushButton#action {
background-color: $COLOR_ACCENT_2;
color: $COLOR_TEXT_1;
border-radius: 6px;
padding: 8px 16px;
&:hover {
background-color: $COLOR_ACCENT_1;
}
}
}
By using these auto-generated theme variables, you create styles that automatically adapt to any theme defined in your JSON configuration, ensuring consistency and making theme switching seamless for your users.
We’re excited to announce the release of Qt Custom Widgets 2.0.1 — a refined update that brings even more power and flexibility to your PyQt and PySide GUI development.
This release focuses on performance improvements, new custom widgets, and a streamlined command-line interface (CLI) that now lets you launch Qt Designer with all custom widgets preloaded.
This version introduces several new widgets designed to enhance both functionality and design flexibility. Each widget can be used directly in Qt Designer or instantiated in Python code, fully integrated with your preferred Qt library (PySide6, PySide2, PyQt6, or PyQt5).
The new CLI now supports launching Qt Designer directly from your environment, with optional loading of all Custom Widgets plugins.
To open Designer with your custom widgets automatically loaded, simply run:
Custom_Widgets --start-designer --plugins
If you prefer to launch Designer without plugins, just run:
Custom_Widgets --start-designer
This feature ensures a seamless integration between your environment and Designer, making your workflow faster and more reliable.
The JSON-based stylesheet system has been updated for better theme management. You can now apply light, dark, or custom themes more efficiently with improved property mapping and rendering accuracy.
This update includes improved logging, faster UI monitoring, and stability enhancements across all supported platforms.
The Custom Widgets CLI is designed to automate repetitive tasks in Qt development. It now supports file monitoring, UI conversion, Designer launching, and project setup — all in one tool.
Custom_Widgets --monitor-ui path/to/file.ui --qt-library PySide6
Automatically converts .ui files to Python when changes are detected.
Custom_Widgets --convert-ui path/to/file.ui --qt-library PySide6
Instantly converts .ui files to .py while preserving all custom widget imports.
Custom_Widgets --start-designer --plugins
Opens Qt Designer with Custom Widgets automatically loaded.
Custom_Widgets --create-project
Sets up a ready-to-use project structure for developing with Qt Custom Widgets.
For detailed command usage:
Custom_Widgets --help
To upgrade to version 2.0.1, run:
pip install --upgrade QT-PyQt-PySide-Custom-Widgets
Or visit the official PyPI page: https://pypi.org/project/QT-PyQt-PySide-Custom-Widgets/