Skip to content
Tutorials Center
My learning

Topics

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.

Java
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.

Java Running a child JVM and reading its output

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.

Java Timeouts, stdin and separate streams

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

Java
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, use redirectErrorStream(true), redirect to a file or DISCARD, or use inheritIO().
  • 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: 0 usually means success; check exitValue() and read stderr for the reason. A killed child reports 128 plus the signal number on Unix.
  • start() throws IOException if the program cannot be found or executed (the message includes the system error).
  • Timeouts: use waitFor(timeout, unit) and then destroy() / destroyForcibly(). Killing a process does not always kill its children; use toHandle().descendants() (Java 9).
  • Platform differences: executable names (dir is a cmd built-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 SecurityManager is gone since Java 24, so there is no sandbox inside the JVM.