Execute and Control System Processes

Tools to run system processes in the background. It can check if a background process is running; wait on a background process to finish; get the exit status of finished processes; kill background processes. It can read the standard output and error of the processes, using non-blocking connections. 'processx' can poll a process for standard output or error, with a timeout. It can also poll several processes at once.

lifecycle Linux Build Status Windows Build status CRAN RStudio mirror downloads Coverage Status

Tools to run system processes in the background, read their standard output and error and kill them.

processx can poll the standard output and error of a single process, or multiple processes, using the operating system's polling and waiting facilities, with a timeout.


  • Start system processes in the background and find their process id.
  • Read the standard output and error, using non-blocking connections
  • Poll the standard output and error connections of a single process or multiple processes.
  • Write to the standard input of background processes.
  • Check if a background process is running.
  • Wait on a background process, or multiple processes, with a timeout.
  • Get the exit status of a background process, if it has already finished.
  • Kill background processes.
  • Kill background process, when its associated object is garbage collected.
  • Kill background processes and all their child processes.
  • Works on Linux, macOS and Windows.
  • Lightweight, it only depends on the also lightweight R6, assertthat and crayon packages.


Install the stable version from CRAN:




Note: the following external commands are usually present in macOS and Linux systems, but not necessarily on Windows. We will also use the px command line tool (px.exe on Windows), that is a very simple program that can produce output to stdout and stderr, with the specified timings.

px <- paste0(
  system.file(package = "processx", "bin", "px"),
  system.file(package = "processx", "bin", .Platform$r_arch, "px.exe")
#> [1] "/Users/gaborcsardi/r_pkgs/processx/bin/px"

Running an external process

The run() function runs an external command. It requires a single command, and a character vector of arguments. You don't need to quote the command or the arguments, as they are passed directly to the operating system, without an intermediate shell.

run("echo", "Hello R!")
#> $status
#> [1] 0
#> $stdout
#> [1] "Hello R!\n"
#> $stderr
#> [1] ""
#> $timeout
#> [1] FALSE

Short summary of the px binary we are using extensively below:

result <- run(px, "--help", echo = TRUE)
#> Usage: px [command arg] [command arg] ...
#> Commands:
#>   sleep  <seconds>           -- sleep for a number os seconds
#>   out    <string>            -- print string to stdout
#>   err    <string>            -- print string to stderr
#>   outln  <string>            -- print string to stdout, add newline
#>   errln  <string>            -- print string to stderr, add newline
#>   cat    <filename>          -- print file to stdout
#>   return <exitcode>          -- return with exitcode
#>   write <fd> <string>        -- write to file descriptor
#>   echo <fd1> <fd2> <nbytes>  -- echo from fd to another fd
#>   getenv <var>               -- environment variable to stdout

Note: From version 3.0.1, processx does not let you specify a full shell command line, as this involves starting a grandchild process from the child process, and it is difficult to clean up the grandchild process when the child process is killed. The user can still start a shell (sh or cmd.exe) directly of course, and then proper cleanup is the user's responsibility.


By default run() throws an error if the process exits with a non-zero status code. To avoid this, specify error_on_status = FALSE:

run(px, c("out", "oh no!", "return", "2"), error_on_status = FALSE)
#> $status
#> [1] 2
#> $stdout
#> [1] "oh no!"
#> $stderr
#> [1] ""
#> $timeout
#> [1] FALSE

Showing output

To show the output of the process on the screen, use the echo argument. Note that the order of stdout and stderr lines may be incorrect, because they are coming from two different connections.

result <- run(px,
  c("outln", "out", "errln", "err", "outln", "out again"),
  echo = TRUE)
#> out
#> out again
#> err

If you have a terminal that support ANSI colors, then the standard error output is shown in red.

The standard output and error are still included in the result of the run() call:

#> $status
#> [1] 0
#> $stdout
#> [1] "out\nout again\n"
#> $stderr
#> [1] "err\n"
#> $timeout
#> [1] FALSE

Note that run() is different from system(), and it always shows the output of the process on R's proper standard output, instead of writing to the terminal directly. This means for example that you can capture the output with capture.output() or use sink(), etc.:

out1 <- capture.output(r1 <- system("ls"))
out2 <- capture.output(r2 <- run("ls", echo = TRUE))
#> character(0)
#>  [1] "CODE_OF_CONDUCT.md" "DESCRIPTION"        "LICENSE"           
#>  [4] "Makefile"           "NAMESPACE"          "NEWS.md"           
#>  [7] "R"                  "README.Rmd"         "README.markdown"   
#> [10] "_pkgdown.yml"       "appveyor.yml"       "docs"              
#> [13] "inst"               "man"                "processx.Rproj"    
#> [16] "src"                "tests"


The spinner option of run() puts a calming spinner to the terminal while the background program is running. The spinner is always shown in the first character of the last line, so you can make it work nicely with the regular output of the background process if you like. E.g. try this in your R terminal:

result <- run(px,
  c("out", "  foo",
    "sleep", "1",
    "out", "\r  bar",
    "sleep", "1",
    "out", "\rX foobar\n"),
  echo = TRUE, spinner = TRUE)

Callbacks for I/O

run() can call an R function for each line of the standard output or error of the process, just supply the stdout_line_callback or the stderr_line_callback arguments. The callback functions take two arguments, the first one is a character scalar, the output line. The second one is the process object that represents the background process. (See more below about process objects.) You can manipulate this object in the callback, if you want. For example you can kill it in response to an error or some text on the standard output:

cb <- function(line, proc) {
  cat("Got:", line, "\n")
  if (line == "done") proc$kill()
result <- run(px,
  c("outln", "this", "outln", "that", "outln", "done",
    "outln", "still here", "sleep", "10", "outln", "dead by now"), 
  stdout_line_callback = cb,
  error_on_status = FALSE,
#> Got: this 
#> Got: that 
#> Got: done 
#> Got: still here
#> $status
#> [1] -9
#> $stdout
#> [1] "this\nthat\ndone\nstill here\n"
#> $stderr
#> [1] ""
#> $timeout
#> [1] FALSE

Keep in mind, that while the R callback is running, the background process is not stopped, it is also running. In the previous example, whether still here is printed or not depends on the scheduling of the R process and the background process by the OS. Typically, it is printed, because the R callback takes a while to run.

In addition to the line-oriented callbacks, the stdout_callback and stderr_callback arguments can specify callback functions that are called with output chunks instead of single lines. A chunk may contain multiple lines (separated by \n or \r\n), or even incomplete lines.

Managing external processes

If you need better control over possibly multiple background processes, then you can use the R6 process class directly.

Starting processes

To start a new background process, create a new instance of the process class.

p <- process$new("sleep", "20")

Killing a process

A process can be killed via the kill() method.

#> [1] TRUE
#> [1] TRUE
#> [1] FALSE

Note that processes are finalized (and killed) automatically if the corresponding process object goes out of scope, as soon as the object is garbage collected by R:

p <- process$new("sleep", "20")
#>          used (Mb) gc trigger (Mb) limit (Mb) max used (Mb)
#> Ncells 428443 22.9     908452 48.6         NA   631340 33.8
#> Vcells 867615  6.7    8388608 64.0      16384  1769037 13.5

Here, the direct call to the garbage collector kills the sleep process as well. See the cleanup option if you want to avoid this behavior.

Standard output and error

By default the standard output and error of the processes are ignored. You can set the stdout and stderr constructor arguments to a file name, and then they are redirected there, or to "|", and then processx creates connections to them. (Note that starting from processx 3.0.0 these connections are not regular R connections, because the public R connection API was retroactively removed from R.)

The read_output_lines() and read_error_lines() methods can be used to read complete lines from the standard output or error connections. They work similarly to the readLines() base R function.

Note, that the connections have a buffer, which can fill up, if R does not read out the output, and then the process will stop, until R reads the connection and the buffer is freed.

Always make sure that you read out the standard output and/or error of the pipes, otherwise the background process will stop running!

If you don't need the standard output or error any more, you can also close it, like this:


Note that the connections used for reading the output and error streams are non-blocking, so the read functions will return immediately, even if there is no text to read from them. If you want to make sure that there is data available to read, you need to poll, see below.

p <- process$new(px,
  c("sleep", "1", "outln", "foo", "errln", "bar", "outln", "foobar"),
  stdout = "|", stderr = "|")
#> character(0)
#> character(0)

End of output

The standard R way to query the end of the stream for a non-blocking connection, is to use the isIncomplete() function. After a read attempt, this function returns FALSE if the connection has surely no more data. (If the read attempt returns no data, but isIncomplete() returns TRUE, then the connection might deliver more data in the future.

The is_incomplete_output() and is_incomplete_error() functions work similarly for process objects.

Polling the standard output and error

The poll_io() method waits for data on the standard output and/or error of a process. It will return if any of the following events happen:

  • data is available on the standard output of the process (assuming there is a connection to the standard output).
  • data is available on the standard error of the proces (assuming the is a connection to the standard error).
  • The process has finished and the standard output and/or error connections were closed on the other end.
  • The specified timeout period expired.

For example the following code waits about a second for output.

p <- process$new(px, c("sleep", "1", "outln", "kuku"), stdout = "|")
## No output yet
#> character(0)
## Wait at most 5 sec
#>   output    error  process 
#>  "ready" "nopipe" "nopipe"
## There is output now
#> [1] "kuku"

Polling multiple processes

If you need to manage multiple background processes, and need to wait for output from all of them, processx defines a poll() function that does just that. It is similar to the poll_io() method, but it takes multiple process objects, and returns as soon as one of them have data on standard output or error, or a timeout expires. Here is an example:

p1 <- process$new(px, c("sleep", "1", "outln", "output"), stdout = "|")
p2 <- process$new(px, c("sleep", "2", "errln", "error"), stderr = "|")
## After 100ms no output yet
poll(list(p1 = p1, p2 = p2), 100)
#> $p1
#>    output     error   process 
#> "timeout"  "nopipe"  "nopipe" 
#> $p2
#>    output     error   process 
#>  "nopipe" "timeout"  "nopipe"
## But now we surely have something
poll(list(p1 = p1, p2 = p2), 1000)
#> $p1
#>   output    error  process 
#>  "ready" "nopipe" "nopipe" 
#> $p2
#>   output    error  process 
#> "nopipe" "silent" "nopipe"
#> [1] "output"
## Done with p1
## The second process should have data on stderr soonish
poll(list(p1 = p1, p2 = p2), 5000)
#> $p1
#>   output    error  process 
#> "closed" "nopipe" "nopipe" 
#> $p2
#>   output    error  process 
#> "nopipe"  "ready" "nopipe"
#> [1] "error"

Waiting on a process

As seen before, is_alive() checks if a process is running. The wait() method can be used to wait until it has finished (or a specified timeout expires).. E.g. in the following code wait() needs to wait about 2 seconds for the sleep px command to finish.

p <- process$new(px, c("sleep", "2"))
#> [1] TRUE
#> [1] "2018-07-24 19:57:33 BST"
#> [1] "2018-07-24 19:57:35 BST"

It is safe to call wait() multiple times:

p$wait() # already finished!

Exit statuses

After a process has finished, its exit status can be queried via the get_exit_status() method. If the process is still running, then this method returns NULL.

p <- process$new(px, c("sleep", "2"))
#> [1] 0


Errors are typically signalled via non-zero exits statuses. The processx constructor fails if the external program cannot be started, but it does not deal with errors that happen after the program has successfully started running.

p <- process$new("nonexistant-command-for-sure")
#> Error in process_initialize(self, private, command, args, stdin, stdout, : processx error: 'No such file or directory' at unix/processx.c:423
p2 <- process$new(px, c("sleep", "1", "command-does-not-exist"))
#> [1] 5

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.


MIT © Mango Solutions, RStudio, Gábor Csárdi


processx 3.3.1

  • Fix a crash on Windows, when a connection that has a pending read internally is finalized.

processx 3.3.0

  • process can now redirect the standard error to the standard output, via specifying stderr = "2>&1". This works both with files and pipes.

  • run() can now redirect the standard error to the standard output, via the new stderr_to_stdout argument.

  • The $kill() and $kill_tree() methods get a close_connection = TRUE argument that closes all pipe connections of the process.

  • run() now always kills the process (and its process tree if cleanup_tree is TRUE) before exiting. This also closes all pipe connections (#149).

processx 3.2.1

  • processx does not depend on assertthat now, and the crayon package is now an optional dependency.

processx 3.2.0

  • New process$kill_tree() method, and new cleanup_tree arguments in run() and process$new(), to clean up the process tree rooted at a processx process. (#139, #143).

  • New process$interupt() method to send an interrupt to a process, SIGINT on Unix, CTRL+C on Windows (#127).

  • New stdin argument in process$new() to support writing to the standard input of a process (#27, #114).

  • New connections argument in process$new() to support passing extra connections to the child process, in addition to the standard streams.

  • New poll_connection argument to process$new(), an extra connection that can be used to poll the process, even if stdout and stderr are not pipes (#125).

  • poll() now works with connections objects, and they can be mixed with process objects (#121).

  • New env argument in run() and process$new(), to set the environment of the child process, optionally (#117, #118).

  • Removed the $restart() method, because it was less useful than expected, and hard to maintain (#116).

  • New conn_set_stdout() and conn_set_stderr() to set the standard output or error of the calling process.

  • New conn_disable_inheritance() to disable stdio inheritance. It is suggested that child processes call this immediately after starting, so the file handles are not inherited further.

  • Fixed a signal handler bug on Unix that marked the process as finished, even if it has not (d221aa1f).

  • Fixed a bug that occasionally caused crashes in wait(), on Unix (#138).

  • When run() is interrupted, no error message is printed, just like for interruption of R code in general. The thrown condition now also has the interrupt class (#148).

processx 3.1.0

  • Fix interference with the parallel package, and other packages that redefine the SIGCHLD signal handler on Unix. If the processx signal handler is overwritten, we might miss the exit status of some processes (they are set to NA).

  • run() and process$new() allow specifying the working directory of the process (#63).

  • Make the debugme package an optional dependency (#74).

  • processx is now compatible with R 3.1.x.

  • Allow polling more than 64 connections on Windows, by using IOCP instead of WaitForMultipleObjects() (#81, #106).

  • Fix a race condition on Windows, when creating named pipes for stdout or stderr. The client sometimes didn't wait for the server, and processx failed with ERROR_PIPE_BUSY (231, All pipe instances are busy).

processx 3.0.3

  • Fix a crash on windows when trying to run a non-existing command (#90)

  • Fix a race condition in process$restart()

  • run() and process$new() do not support the commandline argument any more, because process cleanup is error prone with an intermediate shell. (#88)

  • processx process objects no longer use R connection objects, because the R connection API was retroactive made private by R-core processx uses its own connection class now to manage standard output and error of the process.

  • The encoding of the standard output and error can be specified now, and processx re-encodes stdout and stderr in UTF-8.

  • Cloning of process objects is disables now, as it is likely that it causes problems (@wch).

  • supervise option to kill child process if R crashes (@wch).

  • Add get_output_file and get_error_file, has_output_connection() and has_error_connection() methods (@wch).

  • stdout and stderr default to NULL now, i.e. they are discarded (@wch).

  • Fix undefined behavior when stdout/stderr was read out after the process was already finalized, on Unix.

  • run(): Better message on interruption, kill process when interrupted.

  • Unix: better kill count on unloading the package.

  • Unix: make wait() work when SIGCHLD is not delivered for some reason.

  • Unix: close inherited file descriptors more conservatively.

  • Fix a race condition and several memory leaks on Windows.

  • Fixes when running under job control that does not allow breaking away from the job, on Windows.


This is an unofficial release, created by CRAN, to fix compilation on Solaris.

processx 2.0.0

First public release.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.