The QApplication
object is the core of every Qt Widgets application. Every application needs one and only one QApplication
object to function. This object starts and holds the main event loop of your application which governs all user interaction with the GUI.
When developing applications with PyQt or PySide you will have created an instance of QApplication
like in the example below, passing in sys.argv
or an empty list []
.
- PySide6
- PyQt6
import sys
from PySide6.QtWidgets import QApplication
app = QApplication(sys.argv)
# or: app = QApplication([])
import sys
from PyQt6.QtWidgets import QApplication
app = QApplication(sys.argv)
# or: app = QApplication([])
While this works, you may have asked yourself: what is the meaning of sys.argv
or the empty list []
and why do you need to pass it to QApplication
?
What is sys.argv
?
When your application starts, sys.argv
contains the arguments used to launch your application. If you start a Python application from the command line, sys.argv
will contain the name of your Python script file as the first entry.
The name argv
is an abbreviation of argument vector. This name originates from the C programming language, where "vector" is the name used for a dynamic array or list
.
For example, see the example command line below:
python argtest.py
When executing this script sys.argv
will contain the list ['argtest.py']
. Anything further you add to the end of the command above will be appended to sys.argv
.
Packaging Python Applications with PyInstaller by Martin Fitzpatrick — This step-by-step guide walks you through packaging your own Python applications from simple examples to complete installers and signed executables.
To see this in action create the following simple Python script and save it under the name argtest.py
.
import sys
print("Arguments:", sys.argv)
Now, run your argtest.py
script from the command line and experiment with passing in your own arguments. For example, the following command line:
python argtest.py --info
...will output...
Arguments: ['argtest.py', '--info']
As you can see, the --info
command-line argument is retrieved from sys.argv
, beside the filename of the Python script.
Command-line arguments are split on spaces, so anything separated with a space will be treated as a new argument. To pass arguments that include spaces, you need to wrap those in quotes.
When we pass sys.argv
to QApplication
we are passing the command-line arguments to Qt. This allows us to pass any configuration settings to Qt at the startup of an application.
What command-line arguments are available?
Qt provides some built-in command-line arguments which are also available in PyQt and PySide.
Qt-specific command-line arguments
--platform
platformName[:options] Specifies the Qt Platform Abstraction (QPA) plugin. This overrides the QT_QPA_PLATFORM environment variable.
This is commonly used when developing applications on the Raspberry Pi to redirect Qt output to a linux framebuffer device (e.g. a custom screen) without using XWindows. For example, -platform linuxfb:fb=/dev/fb1
-
--platformpluginpath
path Specifies the path to platform plugins. This overrides the QT_QPA_PLATFORM_PLUGIN_PATH environment variable. -
--platformtheme
theme Specifies the platform theme. This overrides the QT_QPA_PLATFORMTHEME environment variable. -
--plugin
plugin Specifies additional plugins to load. The plugin value may be passed multiple times. This is concatenated with the plugins in the QT_QPA_GENERIC_PLUGINS environment variable. -
--qmljsdebugger
value Activates the QML/JavaScript debugger with a specified port passed as value. The value must be of formatport:1234[,block]
, where block is optional and will make the application wait until a debugger connects to it. -
--qwindowgeometry
geometry Specifies a geometry for the main window using the X11 syntax which should be passed like--qwindowgeometry
100x100+50+50. -
--qwindowicon
icon Sets the default icon of a window. -
--qwindowtitle
title Sets a title of the first window. -
--reverse
Sets the application's layout direction toQt.RightToLeft
. This option is intended to aid debugging and should not be used in production. The default value is automatically detected from the system's locale. -
--session
session Restores the application from an earlier session.
General command-line arguments
-
-h
or--help
or-?
Displays help on all the general command-line arguments, including this one. Note that the-?
argument is only available on Windows. -
--help-all
Displays what--help
does plus all the Qt-specific command-line arguments. -
-v
or--version
Displays the version of an application.
Do I need to pass sys.argv
?
No. While passing sys.argv
allows you to pass command-line configuration through to Qt at the startup of your application, if you don't need or want to prevent configuration of Qt from the command line, you can instead either pass an empty list []
(using PyQt6, PyQt5, PySide2) or nothing at all (using PySide6).
# PyQt6
import sys
from PyQt6.QtWidgets import QApplication
app = QApplication([])
# PySide6
import sys
from PySide6.QtWidgets import QApplication
app = QApplication()
If you do not pass sys.argv
, you are not forwarding command-line arguments to Qt. Therefore, you can not customize Qt's behavior from the command line.
Conclusion
Passing sys.argv
to QApplication
at startup allows you to customize the behavior of
Qt from the command-line. If you don't want to pass command-line arguments to Qt you can skip passing sys.argv
and instead pass nothing (PySide6) or []
(other PyQt or PySide versions).
Be sure to double check if you need any of Qt's command-line configuration — for example, you're developing for Raspberry Pi — before disabling this behavior.
Create GUI Applications with Python & Qt6 by Martin Fitzpatrick — (PyQt6 Edition) The hands-on guide to making apps with Python — Over 10,000 copies sold!