Java Reference ยท java.lang
The ProcessBuilder class
Reference for java.lang.ProcessBuilder: start operating system processes, set arguments, directory and environment, redirect streams, and avoid deadlocks.
java.lang.ProcessBuilder starts operating system processes from Java. You give it a command and arguments as separate strings, configure the working directory, environment and where the standard streams go, then call start() to get a Process handle you can read from, write to, wait for and destroy. It supersedes the old Runtime.exec() string-splitting API.
Arguments are passed to the program as-is. There is no shell involved unless you start one yourself (sh -c, cmd /c), so quotes, wildcards, pipes and $VARIABLES are not interpreted. That is the main reason to prefer it: it avoids command injection from user-supplied values.
Process p = new ProcessBuilder("git", "status", "--short") .directory(new File("/path/to/repo")) .redirectErrorStream(true) .start();
Try it
The online sandbox allows one source file and a restricted process environment, so the programs below start another copy of the running JVM, which is always available. On your own machine, replace the command with any executable.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
public ProcessBuilder(String... command) public ProcessBuilder(List<String> command) public Process start() throws IOException
| Method | Description |
|---|---|
command(String...) / command(List<String>) / command() |
Set or get the program and arguments. |
directory(File) / directory() |
Working directory of the child; default is the current directory of the JVM. |
Map<String,String> environment() |
A modifiable copy of the environment the child will receive. |
redirectErrorStream(boolean) |
Merge stderr into stdout. |
redirectInput/Output/Error(Redirect) |
Send a stream to or from a file, Redirect.PIPE (default), Redirect.INHERIT or DISCARD. |
inheritIO() |
Child uses the JVM's own stdin, stdout and stderr. |
static List<Process> startPipeline(List<ProcessBuilder>) |
Connect several processes like a shell pipe (Java 9). |
Useful Process methods: getInputStream() (child's stdout), getErrorStream(), getOutputStream() (child's stdin), waitFor(), waitFor(long, TimeUnit), exitValue(), isAlive(), destroy(), destroyForcibly(), pid(), toHandle() and onExit() (a CompletableFuture<Process>).
Usage notes
- Read the output while the child runs. If the child fills its stdout or stderr pipe and nobody reads it, it blocks and
waitFor()never returns. Read in separate threads, useredirectErrorStream(true), redirect to a file orDISCARD, or useinheritIO(). - Pass arguments separately:
new ProcessBuilder("ls", "-l", dir), never one concatenated string. This also keeps user input from being interpreted as options or shell syntax; for values that could start with-, put--before them if the program supports it. - To use shell features run the shell explicitly (
"sh", "-c", "ls | wc -l"), and quote values yourself. This reintroduces injection risks. - Exit codes:
0usually means success; checkexitValue()and read stderr for the reason. A killed child reports 128 plus the signal number on Unix. start()throwsIOExceptionif the program cannot be found or executed (the message includes the system error).- Timeouts: use
waitFor(timeout, unit)and thendestroy()/destroyForcibly(). Killing a process does not always kill its children; usetoHandle().descendants()(Java 9). - Platform differences: executable names (
diris acmdbuilt-in, not a program), path separators, line endings and available commands differ between operating systems. - Security: treat the command and environment as trusted data only. A
SecurityManageris gone since Java 24, so there is no sandbox inside the JVM.