Q&A: Why do I need to pass sys.argv or [] when creating an instance of QApplication?

Using command-line arguments to configure Qt
Heads up! You've already completed this tutorial.

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

python
import sys
from PySide6.QtWidgets import QApplication

app = QApplication(sys.argv)
# or: app = QApplication([])
python
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:

bash
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.

More info Get the book

To see this in action create the following simple Python script and save it under the name argtest.py.

python
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:

bash
python argtest.py --info

...will output...

bash
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 format port: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 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.

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

python
# PyQt6

import sys
from PyQt6.QtWidgets import QApplication

app = QApplication([])
python
# 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!

More info Get the book

Well done, you've finished this tutorial! Mark As Complete
[[ user.completed.length ]] completed [[ user.streak+1 ]] day streak

Q&A: Why do I need to pass sys.argv or [] when creating an instance of QApplication? was written by Boštjan Mejak with contributions from Martin Fitzpatrick .

Boštjan Mejak has been developing Python apps for about ten years. He started with Tkinter, then switched to wxPython, PyQt, and recently to PySide.