Skip to content

PythonQt.QtCore.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
Crashed attribute Any
ExitStatus attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
FailedToStart attribute Any
ForwardedChannels attribute Any
ForwardedErrorChannel attribute Any
ForwardedInputChannel attribute Any
ForwardedOutputChannel attribute Any
InputChannelMode attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
ManagedInputChannel attribute Any
MergedChannels attribute Any
NormalExit attribute Any
NotOpen attribute Any (shared captured text)
NotRunning attribute Any
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.
ProcessChannelMode attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
ProcessError attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
ProcessState attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
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
StandardError attribute Any
StandardOutput attribute Any
Starting attribute Any
Text attribute Any (shared captured text)
Timedout attribute Any
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.QtCore.QProcess.aboutToClose; argument details are not documented.
arguments function (self) -> tuple X.arguments() -> tuple
atEnd function (self) -> bool X.atEnd() -> bool
blockSignals function (self, b: Any) -> bool X.blockSignals(b) -> bool (shared captured text)
bytesAvailable function (self) -> int X.bytesAvailable() -> int
bytesToWrite function (self) -> int X.bytesToWrite() -> int
bytesWritten function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtCore.QProcess.bytesWritten; argument details are not documented.
canReadLine function (self) -> bool X.canReadLine() -> bool
channelBytesWritten function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtCore.QProcess.channelBytesWritten; argument details are not documented.
channelReadyRead function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtCore.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)().
closeReadChannel function (self, channel: Any) -> None Closes the read channel channel.
closeWriteChannel function (self) -> None Schedules the write channel of [QProcess](https://doc.qt.io/archives/qt-5.15/qprocess.html) to be closed.
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.QtCore.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
error function (self) -> Any Returns the type of error that occurred last.
errorOccurred function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtCore.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
exitCode function (self) -> int X.exitCode() -> int
exitStatus function (self) -> Any Returns the exit status of the last process that finished.
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.QtCore.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.
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
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.
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
objectName attribute Any (shared captured text)
objectNameChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtCore.QProcess.objectNameChanged; argument details are not documented.
open function (self, mode: Any) -> bool X.open(mode) -> bool
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.
processEnvironment function (self) -> Any X.processEnvironment() -> PythonQt.QtCore.QProcessEnvironment
processId function (self) -> int X.processId() -> int
program function (self) -> str X.program() -> str
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
readAllStandardOutput function (self) -> Any X.readAllStandardOutput() -> PythonQt.QtCore.QByteArray
readChannel function (self) -> Any Returns the current read channel of the [QProcess](https://doc.qt.io/archives/qt-5.15/qprocess.html).
readChannelFinished function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtCore.QProcess.readChannelFinished; argument details are not documented.
readData function (self, data: str, maxlen: int) -> int X.readData(data, maxlen) -> int
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.QtCore.QProcess.readyRead; argument details are not documented.
readyReadStandardError function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtCore.QProcess.readyReadStandardError; argument details are not documented.
readyReadStandardOutput function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtCore.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
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.
setEnvironment function (self, environment: Any) -> None
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.
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.
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.
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.
setProgram function (self, program: str) -> None Set the program to use when starting the process.
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.
setStandardErrorFile function (self, fileName: str, mode: Any) -> None X.setStandardErrorFile(fileName, mode)
setStandardInputFile function (self, fileName: str) -> None Redirects the process' standard input to the file indicated by fileName.
setStandardOutputFile function (self, fileName: str, mode: Any) -> None X.setStandardOutputFile(fileName, mode)
setStandardOutputProcess function (self, destination: Any) -> None Pipes the standard output stream of this process to the destination process' standard input.
setTextModeEnabled function (self, enabled: Any) -> Any (shared captured text)
setWorkingDirectory function (self, dir: str) -> None Sets the working directory to dir.
setupChildProcess function (self) -> None You cannot exit the process (by calling exit(), for instance) from this function.
signalsBlocked function (self) -> bool X.signalsBlocked() -> bool (shared captured text)
size function (self) -> int X.size() -> int
start function (self, program: Any, arguments: Any, mode: Any) -> None X.start(program, arguments, mode)
startDetached function (self, program: Any, arguments: Any, workingDirectory: Any, pid: Any) -> bool X.startDetached(program, arguments, workingDirectory, pid) -> bool
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.QtCore.QProcess.started; argument details are not documented.
state function (self) -> Any Returns the current state of the process.
stateChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtCore.QProcess.stateChanged; argument details are not documented.
systemEnvironment function (self) -> tuple X.systemEnvironment() -> tuple
terminate function (self) -> None Attempts to terminate the process.
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
waitForFinished function (self, msecs: int) -> bool X.waitForFinished(msecs) -> bool
waitForReadyRead function (self, msecs: int) -> bool X.waitForReadyRead(msecs) -> bool
waitForStarted function (self, msecs: int) -> bool X.waitForStarted(msecs) -> bool
workingDirectory function (self) -> str X.workingDirectory() -> str
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