This gem aims at being a simple and reliable solution for controlling external programs running in the background on any Ruby / OS combination.

The code originated in the selenium-webdriver gem, but should prove useful as a standalone library.

Build Status Gem Version Code Climate Coverage Status


The object returned from will implement ChildProcess::AbstractProcess.

Basic examples

process ="ruby", "-e", "sleep")

# inherit stdout/stderr from parent...!

# ...or pass an IO ="child-output")

# modify the environment for the child
process.environment["a"] = "b"
process.environment["c"] = nil

# set the child's working directory
process.cwd = '/some/path'

# start the process

# check process status
process.alive?    #=> true
process.exited?   #=> false

# wait indefinitely for process to exit...
process.exited?   #=> true

# get the exit code
process.exit_code #=> 0

# ...or poll for exit + force quit
rescue ChildProcess::TimeoutError
  process.stop # tries increasingly harsher methods to kill the process.

Advanced examples

Output to pipe

r, w = IO.pipe

proc ="echo", "foo") = = w

  loop { print r.readpartial(8192) }
rescue EOFError


Note that if you just want to get the output of a command, the backtick method on Kernel may be a better fit.

Write to stdin

process ="cat")

out      ="duplex")
out.sync = true = = out
process.duplex    = true # sets up pipe so will be available after .start

process.start "hello world"


out.rewind #=> "hello world\n"

Pipe output to another ChildProcess

search           ="grep", '-E', %w(redis memcached).join('|'))
search.duplex    = true # sets up pipe so will be available after .start = $stdout

listing           ="ps", "aux") =

Prefer posix_spawn on *nix

If the parent process is using a lot of memory, fork+exec can be very expensive. The posix_spawn() API removes this overhead.

ChildProcess.posix_spawn = true
process =*args)

Ensure entire process tree dies

By default, the child process does not create a new process group. This means there's no guarantee that the entire process tree will die when the child process is killed. To solve this:

process =*args)
process.leader = true

Detach from parent

process ="sleep", "10")
process.detach = true

Invoking a shell

As opposed to Kernel#system, Kernel#exec et al., ChildProcess will not automatically execute your command in a shell (like /bin/sh or cmd.exe) depending on the arguments. This means that if you try to execute e.g. gem executables (like bundle or gem) or Windows executables (with .com or .bat extensions) you may see a ChildProcess::LaunchError. You can work around this by being explicit about what interpreter to invoke:"cmd.exe", "/c", "bundle")"ruby", "-S", "bundle")


  • With JRuby on Unix, modifying ENV["PATH"] before using childprocess could lead to 'Command not found' errors, since JRuby is unable to modify the environemnt used for PATH searches in java.lang.ProcessBuilder. This can be avoided by setting ChildProcess.posix_spawn = true.


How the process is launched and killed depends on the platform:

  • Unix : fork + exec (or posix_spawn if enabled)
  • Windows : CreateProcess() and friends
  • JRuby : java.lang.{Process,ProcessBuilder}

Note on Patches/Pull Requests

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so I don't break it in a future version unintentionally.
  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
  • Send me a pull request. Bonus points for topic branches.


Copyright (c) 2010-2015 Jari Bakken. See LICENSE for details.