Skip to content

PythonQt.Qt.QProcess

QProcess

PythonQtInstanceWrapper object

Native bases: PythonQtInstanceWrapper

Supplemental documentation: Qt 5 reference:

Detailed Description

Running a Process

To start a process, pass the name and command line arguments of the program you want to run as arguments to start(). Arguments are supplied as individual strings in a QStringList.

Alternatively, you can set the program to run with setProgram() and setArguments(), and then call start() or open().

For example, the following code snippet runs the analog clock example in the Fusion style on X11 platforms by passing strings containing "-style" and "fusion" as two items in the list of arguments:

    QObject *parent;
    ...
    QString program = "./path/to/Qt/examples/widgets/analogclock";
    QStringList arguments;
    arguments << "-style" << "fusion";

    QProcess *myProcess = new QProcess(parent);
    myProcess->start(program, arguments);

QProcess then enters the Starting state, and when the program has started, QProcess enters the Running state and emits started().

QProcess allows you to treat a process as a sequential I/O device. You can write to and read from the process just as you would access a network connection using QTcpSocket. You can then write to the process's standard input by calling write(), and read the standard output by calling read(), readLine(), and getChar(). Because it inherits QIODevice, QProcess can also be used as an input source for QXmlReader, or for generating data to be uploaded using QNetworkAccessManager.

When the process exits, QProcess reenters the NotRunning state (the initial state), and emits finished().

The finished() signal provides the exit code and exit status of the process as arguments, and you can also call exitCode() to obtain the exit code of the last process that finished, and exitStatus() to obtain its exit status. If an error occurs at any point in time, QProcess will emit the errorOccurred() signal. You can also call error() to find the type of error that occurred last, and state() to find the current process state.

Note: QProcess is not supported on VxWorks, iOS, tvOS, watchOS, or the Universal Windows Platform.

Communicating via Channels

Processes have two predefined output channels: The standard output channel (stdout) supplies regular console output, and the standard error channel (stderr) usually supplies the errors that are printed by the process. These channels represent two separate streams of data. You can toggle between them by calling setReadChannel(). QProcess emits readyRead() when data is available on the current read channel. It also emits readyReadStandardOutput() when new standard output data is available, and when new standard error data is available, readyReadStandardError() is emitted. Instead of calling read(), readLine(), or getChar(), you can explicitly read all data from either of the two channels by calling readAllStandardOutput() or readAllStandardError().

The terminology for the channels can be misleading. Be aware that the process's output channels correspond to QProcess's read channels, whereas the process's input channels correspond to QProcess's write channels. This is because what we read using QProcess is the process's output, and what we write becomes the process's input.

QProcess can merge the two output channels, so that standard output and standard error data from the running process both use the standard output channel. Call setProcessChannelMode() with MergedChannels before starting the process to activate this feature. You also have the option of forwarding the output of the running process to the calling, main process, by passing ForwardedChannels as the argument. It is also possible to forward only one of the output channels - typically one would use ForwardedErrorChannel, but ForwardedOutputChannel also exists. Note that using channel forwarding is typically a bad idea in GUI applications - you should present errors graphically instead.

Certain processes need special environment settings in order to operate. You can set environment variables for your process by calling setProcessEnvironment(). To set a working directory, call setWorkingDirectory(). By default, processes are run in the current working directory of the calling process.

The positioning and the screen Z-order of windows belonging to GUI applications started with QProcess are controlled by the underlying windowing system. For Qt 5 applications, the positioning can be specified using the -qwindowgeometry command line option; X11 applications generally accept a -geometry command line option.

Synchronous Process API

QProcess provides a set of functions which allow it to be used without an event loop, by suspending the calling thread until certain signals are emitted:

Calling these functions from the main thread (the thread that calls QApplication::exec()) may cause your user interface to freeze.

The following example runs gzip to compress the string "Qt rocks!", without an event loop:

    QProcess gzip;
    gzip.start("gzip", QStringList() << "-c");
    if (!gzip.waitForStarted())
        return false;

    gzip.write("Qt rocks!");
    gzip.closeWriteChannel();

    if (!gzip.waitForFinished())
        return false;

    QByteArray result = gzip.readAll();

Notes for Windows Users

Some Windows commands (for example, dir) are not provided by separate applications, but by the command interpreter itself. If you attempt to use QProcess to execute these commands directly, it won't work. One possible solution is to execute the command interpreter itself (cmd.exe on some Windows systems), and ask the interpreter to execute the desired command.

Source: https://doc.qt.io/archives/qt-5.15/qprocess.html

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
Append attribute Any (shared captured text)
CrashExit attribute Any (shared captured text)
Crashed attribute Any (shared captured text)
ExitStatus attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
FailedToStart attribute Any (shared captured text)
ForwardedChannels attribute Any (shared captured text)
ForwardedErrorChannel attribute Any (shared captured text)
ForwardedInputChannel attribute Any (shared captured text)
ForwardedOutputChannel attribute Any (shared captured text)
InputChannelMode attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
ManagedInputChannel attribute Any (shared captured text)
MergedChannels attribute Any (shared captured text)
NormalExit attribute Any (shared captured text)
NotOpen attribute Any (shared captured text)
NotRunning attribute Any (shared captured text)
OpenMode attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
OpenModeFlag attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
ProcessChannel attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
ProcessChannelMode attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
ProcessError attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
ProcessState attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
ReadError attribute Any (shared captured text)
ReadOnly attribute Any (shared captured text)
ReadWrite attribute Any (shared captured text)
Running attribute Any (shared captured text)
SeparateChannels attribute Any (shared captured text)
StandardError attribute Any (shared captured text)
StandardOutput attribute Any (shared captured text)
Starting attribute Any (shared captured text)
Text attribute Any (shared captured text)
Timedout attribute Any (shared captured text)
Truncate attribute Any (shared captured text)
Unbuffered attribute Any (shared captured text)
UnknownError attribute Any (shared captured text)
WriteError attribute Any (shared captured text)
WriteOnly attribute Any (shared captured text)
__init__ function (self, *args: Any, **kwargs: Any) -> None Native constructor; consult class documentation for supported overloads. (shared captured text)
aboutToClose function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.aboutToClose; argument details are not documented.
arguments function (self) -> tuple X.arguments() -> tuple (shared captured text)
atEnd function (self) -> bool X.atEnd() -> bool (shared captured text)
blockSignals function (self, b: Any) -> bool X.blockSignals(b) -> bool (shared captured text)
bytesAvailable function (self) -> int X.bytesAvailable() -> int (shared captured text)
bytesToWrite function (self) -> int X.bytesToWrite() -> int (shared captured text)
bytesWritten function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.bytesWritten; argument details are not documented.
canReadLine function (self) -> bool X.canReadLine() -> bool (shared captured text)
channelBytesWritten function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.channelBytesWritten; argument details are not documented.
channelReadyRead function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.channelReadyRead; argument details are not documented.
childEvent function (self, event: Any) -> Any (shared captured text)
children function (self) -> tuple X.children() -> tuple (shared captured text)
className function (self, *args: Any, **kwargs: Any) -> Any Return the classname of the object (shared captured text)
close function (self) -> None Reimplements: [QIODevice::close](https://doc.qt.io/archives/qt-5.15/qiodevice.html#close)(). (shared captured text)
closeReadChannel function (self, channel: Any) -> None Closes the read channel channel. (shared captured text)
closeWriteChannel function (self) -> None Schedules the write channel of [QProcess](https://doc.qt.io/archives/qt-5.15/qprocess.html) to be closed. (shared captured text)
connect function (self, signal: Any, receiver: Any, slot: Any, type: Any) -> bool X.connect(signal, receiver, slot, type) -> bool (shared captured text)
customEvent function (self, event: Any) -> Any (shared captured text)
delete function (self, *args: Any, **kwargs: Any) -> Any Deletes the C++ object (at your own risk, my friend!) (shared captured text)
deleteLater function (self) -> Any (shared captured text)
destroyed function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.destroyed; argument details are not documented.
disconnect function (self, signal: Any, receiver: Any, slot: Any) -> bool X.disconnect(signal, receiver, slot) -> bool (shared captured text)
dumpObjectInfo function (self) -> Any (shared captured text)
dumpObjectTree function (self) -> Any (shared captured text)
dynamicPropertyNames function (self) -> Any (shared captured text)
environment function (self) -> tuple X.environment() -> tuple (shared captured text)
error function (self) -> Any Returns the type of error that occurred last. (shared captured text)
errorOccurred function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.errorOccurred; argument details are not documented.
errorString function (self) -> str X.errorString() -> str (shared captured text)
event function (self, event: Any) -> bool X.event(event) -> bool (shared captured text)
eventFilter function (self, watched: Any, event: Any) -> bool X.eventFilter(watched, event) -> bool (shared captured text)
execute function (self, program: Any, arguments: Any) -> int X.execute(program, arguments) -> int (shared captured text)
exitCode function (self) -> int X.exitCode() -> int (shared captured text)
exitStatus function (self) -> Any Returns the exit status of the last process that finished. (shared captured text)
findChild function (self, type: Any, name: Any) -> Any X.findChild(type, name) -> PythonQt.private.QObject (shared captured text)
findChildren function (self, type: Any, name: Any) -> tuple X.findChildren(type, name) -> tuple (shared captured text)
finished function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.finished; argument details are not documented.
getChar function (self, c: Any) -> bool X.getChar(c) -> bool (shared captured text)
help function (self, *args: Any, **kwargs: Any) -> Any Shows the help of available methods for this class (shared captured text)
inherits function (self, *args: Any, **kwargs: Any) -> Any Returns if the class inherits or is of given type name (shared captured text)
inputChannelMode function (self) -> Any Returns the channel mode of the [QProcess](https://doc.qt.io/archives/qt-5.15/qprocess.html) standard input channel. (shared captured text)
installEventFilter function (self, filterObj: Any) -> Any (shared captured text)
isOpen function (self) -> bool X.isOpen() -> bool (shared captured text)
isReadable function (self) -> bool X.isReadable() -> bool (shared captured text)
isSequential function (self) -> bool X.isSequential() -> bool (shared captured text)
isSignalConnected function (self, signal: Any) -> bool X.isSignalConnected(signal) -> bool (shared captured text)
isTextModeEnabled function (self) -> bool X.isTextModeEnabled() -> bool (shared captured text)
isWidgetType function (self) -> bool X.isWidgetType() -> bool (shared captured text)
isWindowType function (self) -> bool X.isWindowType() -> bool (shared captured text)
isWritable function (self) -> bool X.isWritable() -> bool (shared captured text)
kill function (self) -> None Kills the current process, causing it to exit immediately. (shared captured text)
killTimer function (self, id: Any) -> Any (shared captured text)
metaObject function (self) -> Any X.metaObject() -> PythonQt.QtCore.QMetaObject (shared captured text)
moveToThread function (self, thread: Any) -> Any (shared captured text)
nullDevice function (self) -> str X.nullDevice() -> str (shared captured text)
objectName attribute Any (shared captured text)
objectNameChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.objectNameChanged; argument details are not documented.
open function (self, mode: Any) -> bool X.open(mode) -> bool (shared captured text)
openMode function (self) -> Any (shared captured text)
parent function (self) -> Any X.parent() -> PythonQt.private.QObject (shared captured text)
peek function (self, maxlen: Any) -> Any X.peek(maxlen) -> PythonQt.QtCore.QByteArray (shared captured text)
pos function (self) -> int X.pos() -> int (shared captured text)
processChannelMode function (self) -> Any Returns the channel mode of the [QProcess](https://doc.qt.io/archives/qt-5.15/qprocess.html) standard output and standard error channels. (shared captured text)
processEnvironment function (self) -> Any X.processEnvironment() -> PythonQt.QtCore.QProcessEnvironment (shared captured text)
processId function (self) -> int X.processId() -> int (shared captured text)
program function (self) -> str X.program() -> str (shared captured text)
property function (self, name: Any) -> Any X.property(name) -> object (shared captured text)
putChar function (self, c: Any) -> bool X.putChar(c) -> bool (shared captured text)
read function (self, maxlen: Any) -> Any X.read(maxlen) -> PythonQt.QtCore.QByteArray (shared captured text)
readAll function (self) -> Any X.readAll() -> PythonQt.QtCore.QByteArray (shared captured text)
readAllStandardError function (self) -> Any X.readAllStandardError() -> PythonQt.QtCore.QByteArray (shared captured text)
readAllStandardOutput function (self) -> Any X.readAllStandardOutput() -> PythonQt.QtCore.QByteArray (shared captured text)
readChannel function (self) -> Any Returns the current read channel of the [QProcess](https://doc.qt.io/archives/qt-5.15/qprocess.html). (shared captured text)
readChannelFinished function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.readChannelFinished; argument details are not documented.
readData function (self, data: str, maxlen: int) -> int X.readData(data, maxlen) -> int (shared captured text)
readLine function (self, maxlen: Any) -> Any X.readLine(maxlen) -> PythonQt.QtCore.QByteArray (shared captured text)
readLineData function (self, data: Any, maxlen: Any) -> int X.readLineData(data, maxlen) -> int (shared captured text)
readyRead function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.readyRead; argument details are not documented.
readyReadStandardError function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.readyReadStandardError; argument details are not documented.
readyReadStandardOutput function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.readyReadStandardOutput; argument details are not documented.
removeEventFilter function (self, obj: Any) -> Any (shared captured text)
reset function (self) -> bool X.reset() -> bool (shared captured text)
seek function (self, pos: Any) -> bool X.seek(pos) -> bool (shared captured text)
sender function (self) -> Any X.sender() -> PythonQt.private.QObject (shared captured text)
senderSignalIndex function (self) -> int X.senderSignalIndex() -> int (shared captured text)
setArguments function (self, arguments: Any) -> None Set the arguments to pass to the called program when starting the process. (shared captured text)
setEnvironment function (self, environment: Any) -> None (shared captured text)
setErrorString function (self, errorString: Any) -> Any (shared captured text)
setInputChannelMode function (self, mode: Any) -> None Sets the channel mode of the [QProcess](https://doc.qt.io/archives/qt-5.15/qprocess.html) standard input channel to the mode specified. (shared captured text)
setObjectName function (self, name: Any) -> Any (shared captured text)
setOpenMode function (self, openMode: Any) -> Any (shared captured text)
setParent function (self, parent: Any) -> Any (shared captured text)
setProcessChannelMode function (self, mode: Any) -> None This function was introduced in Qt 4.2. (shared captured text)
setProcessEnvironment function (self, environment: Any) -> None Sets the environment that [QProcess](https://doc.qt.io/archives/qt-5.15/qprocess.html) will pass to the child process. (shared captured text)
setProcessState function (self, state: Any) -> None Sets the current state of the [QProcess](https://doc.qt.io/archives/qt-5.15/qprocess.html) to the state specified. (shared captured text)
setProgram function (self, program: str) -> None Set the program to use when starting the process. (shared captured text)
setProperty function (self, name: Any, value: Any) -> bool X.setProperty(name, value) -> bool (shared captured text)
setReadChannel function (self, channel: Any) -> None Sets the current read channel of the [QProcess](https://doc.qt.io/archives/qt-5.15/qprocess.html) to the given channel. (shared captured text)
setStandardErrorFile function (self, fileName: str, mode: Any) -> None X.setStandardErrorFile(fileName, mode) (shared captured text)
setStandardInputFile function (self, fileName: str) -> None Redirects the process' standard input to the file indicated by fileName. (shared captured text)
setStandardOutputFile function (self, fileName: str, mode: Any) -> None X.setStandardOutputFile(fileName, mode) (shared captured text)
setStandardOutputProcess function (self, destination: Any) -> None Pipes the standard output stream of this process to the destination process' standard input. (shared captured text)
setTextModeEnabled function (self, enabled: Any) -> Any (shared captured text)
setWorkingDirectory function (self, dir: str) -> None Sets the working directory to dir. (shared captured text)
setupChildProcess function (self) -> None You cannot exit the process (by calling exit(), for instance) from this function. (shared captured text)
signalsBlocked function (self) -> bool X.signalsBlocked() -> bool (shared captured text)
size function (self) -> int X.size() -> int (shared captured text)
start function (self, program: Any, arguments: Any, mode: Any) -> None X.start(program, arguments, mode) (shared captured text)
startDetached function (self, program: Any, arguments: Any, workingDirectory: Any, pid: Any) -> bool X.startDetached(program, arguments, workingDirectory, pid) -> bool (shared captured text)
startTimer function (self, interval: Any, timerType: Any) -> int X.startTimer(interval, timerType) -> int (shared captured text)
started function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.started; argument details are not documented.
state function (self) -> Any Returns the current state of the process. (shared captured text)
stateChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QProcess.stateChanged; argument details are not documented.
systemEnvironment function (self) -> tuple X.systemEnvironment() -> tuple (shared captured text)
terminate function (self) -> None Attempts to terminate the process. (shared captured text)
thread function (self) -> Any (shared captured text)
timerEvent function (self, event: Any) -> Any (shared captured text)
tr function (self, text: Any, ambig: Any, n: Any) -> str X.tr(text, ambig, n) -> str (shared captured text)
ungetChar function (self, c: Any) -> Any (shared captured text)
waitForBytesWritten function (self, msecs: int) -> bool X.waitForBytesWritten(msecs) -> bool (shared captured text)
waitForFinished function (self, msecs: int) -> bool X.waitForFinished(msecs) -> bool (shared captured text)
waitForReadyRead function (self, msecs: int) -> bool X.waitForReadyRead(msecs) -> bool (shared captured text)
waitForStarted function (self, msecs: int) -> bool X.waitForStarted(msecs) -> bool (shared captured text)
workingDirectory function (self) -> str X.workingDirectory() -> str (shared captured text)
write function (self, data: Any) -> int X.write(data) -> int (shared captured text)
writeData function (self, data: str, len: int) -> int X.writeData(data, len) -> int (shared captured text)