Python GUIs: Why do I need to pass sys.argv or [] when creating an instance of QApplication?other missing modules

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 [].

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.

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

• --platformplatformName[: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

• --platformpluginpathpath Specifies the path to platform plugins. This overrides the QT_QPA_PLATFORM_PLUGIN_PATH environment variable.

• --platformthemetheme Specifies the platform theme. This overrides the QT_QPA_PLATFORMTHEME environment variable.

• --pluginplugin 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.

• --qmljsdebuggervalue Activates the QML/JavaScript debugger with a specified port passed as value. The value must be of format port:1234[,block], where block is optional and will make the application wait until a debugger connects to it.

• --qwindowgeometrygeometry Specifies a geometry for the main window using the X11 syntax which should be passed like --qwindowgeometry100x100+50+50.

• --qwindowiconicon Sets the default icon of a window.

• --qwindowtitletitle Sets a title of the first window.

• --reverse Sets the application's layout direction to Qt.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.

• --sessionsession 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.

For an in-depth guide to building GUIs with Python see my PyQt book.