{"id":13423484,"url":"https://github.com/r-lib/processx","last_synced_at":"2025-05-14T11:12:32.124Z","repository":{"id":37951271,"uuid":"66083698","full_name":"r-lib/processx","owner":"r-lib","description":"Execute and Control Subprocesses from R","archived":false,"fork":false,"pushed_at":"2025-04-26T15:05:47.000Z","size":10839,"stargazers_count":238,"open_issues_count":24,"forks_count":43,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-14T05:38:40.940Z","etag":null,"topics":["r"],"latest_commit_sha":null,"homepage":"https://processx.r-lib.org/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/r-lib.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-08-19T13:18:57.000Z","updated_at":"2025-05-11T13:13:02.000Z","dependencies_parsed_at":"2023-02-17T00:01:34.010Z","dependency_job_id":"1ac2fb7f-3d11-4bb6-a7d7-f9c7a421f91e","html_url":"https://github.com/r-lib/processx","commit_stats":{"total_commits":1149,"total_committers":18,"mean_commits":"63.833333333333336","dds":0.09399477806788514,"last_synced_commit":"c3ab227336a552319633a0fee528a1e7df1f2f44"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fprocessx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fprocessx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fprocessx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fprocessx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r-lib","download_url":"https://codeload.github.com/r-lib/processx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254117143,"owners_count":22017755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["r"],"created_at":"2024-07-31T00:00:35.697Z","updated_at":"2025-05-14T11:12:27.107Z","avatar_url":"https://github.com/r-lib.png","language":"R","funding_links":[],"categories":["C","R"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n```{r, setup, echo = FALSE, message = FALSE}\nknitr::opts_chunk$set(\n  comment = \"#\u003e\",\n  tidy = FALSE,\n  error = FALSE,\n  fig.width = 8,\n  fig.height = 8)\n```\n\n# processx\n\n\u003e Execute and Control System Processes\n\n\u003c!-- badges: start --\u003e\n[![lifecycle](https://lifecycle.r-lib.org/articles/figures/lifecycle-stable.svg)](https://lifecycle.r-lib.org/articles/stages.html)\n[![R-CMD-check](https://github.com/r-lib/processx/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/processx/actions/workflows/R-CMD-check.yaml)\n[![](https://www.r-pkg.org/badges/version/processx)](https://www.r-pkg.org/pkg/processx)\n[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/processx)](https://www.r-pkg.org/pkg/processx)\n[![Codecov test coverage](https://codecov.io/gh/r-lib/processx/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/processx?branch=main)\n\u003c!-- badges: end --\u003e\n\nTools to run system processes in the background,\nread their standard output and error and kill them.\n\nprocessx can poll the standard output and error of a single process,\nor multiple processes, using the operating system's polling and waiting\nfacilities, with a timeout.\n\n---\n\n   * [Features](#features)\n   * [Installation](#installation)\n   * [Usage](#usage)\n      * [Running an external process](#running-an-external-process)\n         * [Errors](#errors)\n         * [Showing output](#showing-output)\n         * [Spinner](#spinner)\n         * [Callbacks for I/O](#callbacks-for-io)\n      * [Managing external processes](#managing-external-processes)\n         * [Starting processes](#starting-processes)\n         * [Killing a process](#killing-a-process)\n         * [Standard output and error](#standard-output-and-error)\n         * [End of output](#end-of-output)\n         * [Polling the standard output and error](#polling-the-standard-output-and-error)\n         * [Polling multiple processes](#polling-multiple-processes)\n         * [Waiting on a process](#waiting-on-a-process)\n         * [Exit statuses](#exit-statuses)\n         * [Mixing processx and the parallel base R package](#mixing-processx-and-the-parallel-base-r-package)\n         * [Errors](#errors-1)\n   * [Related tools](#related-tools)\n   * [Code of Conduct](#code-of-conduct)\n   * [License](#license)\n\n## Features\n\n* Start system processes in the background and find their\n  process id.\n* Read the standard output and error, using non-blocking connections\n* Poll the standard output and error connections of a single process or\n  multiple processes.\n* Write to the standard input of background processes.\n* Check if a background process is running.\n* Wait on a background process, or multiple processes, with a timeout.\n* Get the exit status of a background process, if it has already\n  finished.\n* Kill background processes.\n* Kill background process, when its associated object is garbage\n  collected.\n* Kill background processes and all their child processes.\n* Works on Linux, macOS and Windows.\n* Lightweight, it only depends on the also lightweight\n  R6 and ps packages.\n\n## Installation\n\nInstall the stable version from CRAN:\n\n```{r eval = FALSE}\ninstall.packages(\"processx\")\n```\n\nIf you need the development version, install it from GitHub:\n\n```{r eval = FALSE}\npak::pak(\"r-lib/processx\")\n```\n\n## Usage\n\n```{r}\nlibrary(processx)\n```\n\n\u003e Note: the following external commands are usually present in macOS and\n\u003e Linux systems, but not necessarily on Windows. We will also use the `px`\n\u003e command line tool (`px.exe` on Windows), that is a very simple program\n\u003e that can produce output to `stdout` and `stderr`, with the specified\n\u003e timings.\n\n```{r}\npx \u003c- paste0(\n  system.file(package = \"processx\", \"bin\", \"px\"),\n  system.file(package = \"processx\", \"bin\", .Platform$r_arch, \"px.exe\")\n)\npx\n```\n\n### Running an external process\n\nThe `run()` function runs an external command. It requires a single command,\nand a character vector of arguments. You don't need to quote the command\nor the arguments, as they are passed directly to the operating system,\nwithout an intermediate shell.\n\n```{r}\nrun(\"echo\", \"Hello R!\")\n```\n\nShort summary of the `px` binary we are using extensively below:\n```{r}\nresult \u003c- run(px, \"--help\", echo = TRUE)\n```\n\n\u003e Note: From version 3.0.1, processx does not let you specify a full\n\u003e shell command line, as this involves starting a grandchild process from\n\u003e the child process, and it is difficult to clean up the grandchild\n\u003e process when the child process is killed. The user can still start a\n\u003e shell (`sh` or `cmd.exe`) directly of course, and then proper cleanup is\n\u003e the user's responsibility.\n\n#### Errors\n\nBy default `run()` throws an error if the process exits with a non-zero\nstatus code. To avoid this, specify `error_on_status = FALSE`:\n\n```{r}\nrun(px, c(\"out\", \"oh no!\", \"return\", \"2\"), error_on_status = FALSE)\n```\n\n#### Showing output\n\nTo show the output of the process on the screen, use the `echo` argument.\nNote that the order of `stdout` and `stderr` lines may be incorrect,\nbecause they are coming from two different connections.\n\n```{r}\nresult \u003c- run(px,\n  c(\"outln\", \"out\", \"errln\", \"err\", \"outln\", \"out again\"),\n  echo = TRUE)\n```\n\nIf you have a terminal that support ANSI colors, then the standard error\noutput is shown in red.\n\nThe standard output and error are still included in the result of the\n`run()` call:\n\n```{r}\nresult\n```\n\nNote that `run()` is different from `system()`, and it always shows the\noutput of the process on R's proper standard output, instead of writing to\nthe terminal directly. This means for example that you can capture the\noutput with `capture.output()` or use `sink()`, etc.:\n\n```{r}\nout1 \u003c- capture.output(r1 \u003c- system(\"ls\"))\nout2 \u003c- capture.output(r2 \u003c- run(\"ls\", echo = TRUE))\n```\n\n```{r}\nout1\nout2\n```\n\n#### Spinner\n\nThe `spinner` option of `run()` puts a calming spinner to the terminal\nwhile the background program is running. The spinner is always shown in the\nfirst character of the last line, so you can make it work nicely with the\nregular output of the background process if you like. E.g. try this in your\nR terminal:\n\n```\nresult \u003c- run(px,\n  c(\"out\", \"  foo\",\n    \"sleep\", \"1\",\n    \"out\", \"\\r  bar\",\n\t\"sleep\", \"1\",\n\t\"out\", \"\\rX foobar\\n\"),\n  echo = TRUE, spinner = TRUE)\n```\n\n#### Callbacks for I/O\n\n`run()` can call an R function for each line of the standard output or\nerror of the process, just supply the `stdout_line_callback` or the\n`stderr_line_callback` arguments. The callback functions take two\narguments, the first one is a character scalar, the output line. The\nsecond one is the `process` object that represents the background\nprocess. (See more below about `process` objects.) You can manipulate\nthis object in the callback, if you want. For example you can kill it in\nresponse to an error or some text on the standard output:\n\n```{r, error = TRUE}\ncb \u003c- function(line, proc) {\n  cat(\"Got:\", line, \"\\n\")\n  if (line == \"done\") proc$kill()\n}\nresult \u003c- run(px,\n  c(\"outln\", \"this\", \"outln\", \"that\", \"outln\", \"done\",\n    \"outln\", \"still here\", \"sleep\", \"10\", \"outln\", \"dead by now\"), \n  stdout_line_callback = cb,\n  error_on_status = FALSE,\n)\nresult\n```\n\nKeep in mind, that while the R callback is running, the background process\nis not stopped, it is also running. In the previous example, whether\n`still here` is printed or not depends on the scheduling of the\nR process and the background process by the OS. Typically, it is printed,\nbecause the R callback takes a while to run.\n\nIn addition to the line-oriented callbacks, the `stdout_callback` and\n`stderr_callback` arguments can specify callback functions that are called\nwith output chunks instead of single lines. A chunk may contain multiple\nlines (separated by `\\n` or `\\r\\n`), or even incomplete lines.\n\n### Managing external processes\n\nIf you need better control over possibly multiple background processes,\nthen you can use the R6 `process` class directly.\n\n#### Starting processes\n\nTo start a new background process, create a new instance of the `process`\nclass.\n\n```{r}\np \u003c- process$new(\"sleep\", \"20\")\n```\n\n#### Killing a process\n\nA process can be killed via the `kill()` method.\n\n```{r}\np$is_alive()\np$kill()\np$is_alive()\n```\n\nNote that processes are finalized (and killed) automatically if the\ncorresponding `process` object goes out of scope, as soon as the object\nis garbage collected by R:\n\n```{r}\np \u003c- process$new(\"sleep\", \"20\")\nrm(p)\ninvisible(gc())\n```\n\nHere, the direct call to the garbage collector kills the `sleep` process\nas well. See the `cleanup` option if you want to avoid this behavior.\n\n#### Standard output and error\n\nBy default the standard output and error of the processes are ignored.\nYou can set the `stdout` and `stderr` constructor arguments to a file name,\nand then they are redirected there, or to `\"|\"`, and then processx creates\nconnections to them. (Note that starting from processx 3.0.0 these\nconnections are not regular R connections, because the public R connection\nAPI was retroactively removed from R.)\n\nThe `read_output_lines()` and `read_error_lines()` methods can be used\nto read complete lines from the standard output or error connections. They\nwork similarly to the `readLines()` base R function.\n\nNote, that the connections have a buffer, which can fill up, if R does\nnot read out the output, and then the process will stop, until R reads the\nconnection and the buffer is freed.\n\n\u003e **Always make sure that you read out the standard output and/or error**\n\u003e **of the pipes, otherwise the background process will stop running!**\n\nIf you don't need the standard output or error any more, you can also\nclose it, like this:\n```r\nclose(p$get_output_connection())\nclose(p$get_error_connection())\n```\n\nNote that the connections used for reading the output and error streams\nare non-blocking, so the read functions will return immediately, even if\nthere is no text to read from them. If you want to make sure that there\nis data available to read, you need to poll, see below.\n\n```{r}\np \u003c- process$new(px,\n  c(\"sleep\", \"1\", \"outln\", \"foo\", \"errln\", \"bar\", \"outln\", \"foobar\"),\n  stdout = \"|\", stderr = \"|\")\np$read_output_lines()\np$read_error_lines()\n```\n\n#### End of output\n\nThe standard R way to query the end of the stream for a non-blocking\nconnection, is to use the `isIncomplete()` function. *After a read attempt*,\nthis function returns `FALSE` if the connection has surely no more data.\n(If the read attempt returns no data, but `isIncomplete()` returns `TRUE`,\nthen the connection might deliver more data in the future.\n\nThe `is_incomplete_output()` and `is_incomplete_error()` functions work\nsimilarly for `process` objects.\n\n#### Polling the standard output and error\n\nThe `poll_io()` method waits for data on the standard output and/or error\nof a process. It will return if any of the following events happen:\n\n* data is available on the standard output of the process (assuming there is\n  a connection to the standard output).\n* data is available on the standard error of the process (assuming the is\n  a connection to the standard error).\n* The process has finished and the standard output and/or error connections\n  were closed on the other end.\n* The specified timeout period expired.\n\nFor example the following code waits about a second for output.\n\n```{r}\np \u003c- process$new(px, c(\"sleep\", \"1\", \"outln\", \"kuku\"), stdout = \"|\")\n\n## No output yet\np$read_output_lines()\n\n## Wait at most 5 sec\np$poll_io(5000)\n\n## There is output now\np$read_output_lines()\n```\n\n#### Polling multiple processes\n\nIf you need to manage multiple background processes, and need to wait\nfor output from all of them, processx defines a `poll()` function that\ndoes just that. It is similar to the `poll_io()` method, but it takes\nmultiple process objects, and returns as soon as one of them have data\non standard output or error, or a timeout expires. Here is an example:\n\n```{r}\np1 \u003c- process$new(px, c(\"sleep\", \"1\", \"outln\", \"output\"), stdout = \"|\")\np2 \u003c- process$new(px, c(\"sleep\", \"2\", \"errln\", \"error\"), stderr = \"|\")\n\n## After 100ms no output yet\npoll(list(p1 = p1, p2 = p2), 100)\n\n## But now we surely have something\npoll(list(p1 = p1, p2 = p2), 1000)\np1$read_output_lines()\n\n## Done with p1\nclose(p1$get_output_connection())\n\n## The second process should have data on stderr soonish\npoll(list(p1 = p1, p2 = p2), 5000)\np2$read_error_lines()\n```\n\n#### Waiting on a process\n\nAs seen before, `is_alive()` checks if a process is running. The `wait()`\nmethod can be used to wait until it has finished (or a specified timeout\nexpires).. E.g. in the following code `wait()` needs to wait about 2 seconds\nfor the `sleep` `px` command to finish.\n\n```{r}\np \u003c- process$new(px, c(\"sleep\", \"2\"))\np$is_alive()\nSys.time()\np$wait()\nSys.time()\n```\n\nIt is safe to call `wait()` multiple times:\n\n```{r}\np$wait() # already finished!\n```\n\n#### Exit statuses\n\nAfter a process has finished, its exit status can be queried via the\n`get_exit_status()` method. If the process is still running, then this\nmethod returns `NULL`.\n\n```{r}\np \u003c- process$new(px, c(\"sleep\", \"2\"))\np$get_exit_status()\np$wait()\np$get_exit_status()\n```\n\n#### Mixing processx and the parallel base R package\n\nIn general, mixing processx (via callr or not) and parallel works fine.\nIf you use parallel's 'fork' clusters, e.g. via `parallel::mcparallel()`,\nthen you might see two issues. One is that processx will not be able to\ndetermine the exit status of some processx processes. This is because the\nstatus is read out by parallel, and processx will set it to `NA`. The other\none is that parallel might complain that it could not clean up some\nsubprocesses. This is not an error, and it is harmless, but it does\nhold up R for about 10 seconds, before parallel gives up. To work around\nthis, you can set the `PROCESSX_NOTIFY_OLD_SIGCHLD` environment variable\nto a non-empty value, before you load processx. This behavior might be\nthe default in the future.\n\n#### Errors\n\nErrors are typically signalled via non-zero exits statuses. The processx\nconstructor fails if the external program cannot be started,\nbut it does not deal with errors that happen after the\nprogram has successfully started running.\n\n```{r, error = TRUE}\np \u003c- process$new(\"nonexistant-command-for-sure\")\n```\n\n```{r}\np2 \u003c- process$new(px, c(\"sleep\", \"1\", \"command-does-not-exist\"))\np2$wait()\np2$get_exit_status()\n```\n\n## Related tools\n\n* The [`ps` package](https://ps.r-lib.org/) can query, list, manipulate\n  all system processes (not just subprocesses), and processx uses it\n  internally for some of its functionality. You can also convert a\n  `processx::process` object to a `ps::ps_handle` with the `as_ps_handle()`\n  method.\n\n* The [`callr` package](https://callr.r-lib.org/) uses processx to start\n  another R process, and run R code in it, in the foreground or background.\n\n## Code of Conduct\n\nPlease note that the processx project is released with a\n[Contributor Code of Conduct](https://processx.r-lib.org/CODE_OF_CONDUCT.html).\nBy contributing to this project, you agree to abide by its terms.\n\n## License\n\nMIT © Ascent Digital Services, RStudio, Gábor Csárdi\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-lib%2Fprocessx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr-lib%2Fprocessx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-lib%2Fprocessx/lists"}