Crate duct

source ·
Expand description

Duct is a library for running child processes. Duct makes it easy to build pipelines and redirect IO like a shell. At the same time, Duct helps you write correct, portable code: whitespace is never significant, errors from child processes get reported by default, and a variety of gotchas, bugs, and platform inconsistencies are handled for you the Right Way™.


Run a command without capturing any output. Here “hi” is printed directly to the terminal:

use duct::cmd;
cmd!("echo", "hi").run()?;

Capture the standard output of a command. Here “hi” is returned as a String:

let stdout = cmd!("echo", "hi").read()?;
assert_eq!(stdout, "hi");

Capture the standard output of a pipeline:

let stdout = cmd!("echo", "hi").pipe(cmd!("sed", "s/i/o/")).read()?;
assert_eq!(stdout, "ho");

Merge standard error into standard output and read both incrementally:

use duct::cmd;
use std::io::prelude::*;
use std::io::BufReader;

let big_cmd = cmd!("bash", "-c", "echo out && echo err 1>&2");
let reader = big_cmd.stderr_to_stdout().reader()?;
let mut lines = BufReader::new(reader).lines();
assert_eq!(, "out");
assert_eq!(, "err");

Children that exit with a non-zero status return an error by default:

let result = cmd!("false").run();
let result = cmd!("false").unchecked().run();


Unix-specific extensions to duct, for sending signals.


Create a command with any number of of positional arguments, which may be different types (anything that implements Into<OsString>). See also the cmd function, which takes a collection of arguments.


The central objects in Duct, Expressions are created with cmd or cmd!, combined with pipe, and finally executed with run, read, start, or reader. They also support several methods to control their execution, like stdin_bytes, stdout_capture, env, and unchecked.
A handle to a running expression, returned by the start method.
An incremental reader created with the Expression::reader method.


An implementation detail of cmd, to distinguish paths from other string types.


Create a command given a program name and a collection of arguments. See also the cmd! macro, which doesn’t require a collection.