rusty-pv

Pipe viewer. A Rust port of Andrew Wood's pv(1) — show progress, elapsed time, ETA, rate, and bytes transferred while data flows through a pipe.

Part of the Rusty portfolio.

Install

cargo install rusty-pv
# or, with prebuilt binaries:
cargo binstall rusty-pv

Usage

# Show progress copying a file
rusty-pv ubuntu.iso > /dev/sdb

# Throttle to 5 MiB/s
rusty-pv -L 5M big.iso > out.iso

# Pipe through with a labelled progress line
some-cmd | rusty-pv -N "stage 1" | another-cmd

# Numeric mode for dialog --gauge integration
rusty-pv -n -s 100M big.iso > out.iso

Cargo Features

Feature	Default	What it gates
`cli`	yes	`clap` + `clap_complete` + `anyhow` + `crossterm` + `signal-hook` (Unix) + `fd-lock`

Library consumers can use rusty-pv = { version = "0.1", default-features = false } to get the throttle, EMA, and unit-suffix math without any CLI dependencies.

Library API

use rusty_pv::{Pv, PvBuilder};
use std::io::Cursor;

let pv = PvBuilder::new()
    .total_bytes(1024 * 1024)
    .rate_limit(500_000) // 500 kB/s
    .build();
let mut reader = Cursor::new(vec![0u8; 1024 * 1024]);
let mut writer = Vec::new();
let n = pv.copy(&mut reader, &mut writer).unwrap();
assert_eq!(n, 1024 * 1024);

Compatibility

rusty-pv has two modes:

Default — clap-styled flag parser; rejects conflicting flag pairs at parse time; adds --help, --version, completions subcommand.
Strict (--strict, env RUSTY_PV_STRICT=1, or argv[0] = pv/pv-alias) — byte-equal stderr against upstream v1.10.5 for documented diagnostics; last-wins flag resolution; no subcommands.

v0.1.0 excludes: -F (custom format strings), -T (buffer percentage), -A (peek window), --bits, --remote/--query inter-instance control, SIGUSR2 (deprecated by upstream).

The EMA smoothing constant α = 0.3 is locked at v0.1.0 to preserve byte-equal Strict-mode compatibility; future versions may expose it via an additive library method.

Display modes

Single-line redraw (default) — carriage-return + erase-to-EOL ANSI sequence; works on every terminal that supports basic ANSI.
Cursor mode (-c) — Unix-only in v0.1.0. Coordinates multiple rusty-pv instances in a pipeline so each writes to its own row. Windows emits a stderr diagnostic and falls back to single-line redraw.

Concurrency

The -c per-tty file lock guarantees only one rusty-pv instance writes ANSI cursor escapes at a time, but the cursor-mode design is not crash-safe — if a rusty-pv instance is killed mid-redraw the next surviving instance may briefly overwrite its row. This matches upstream pv behavior.

MSRV

Rust 1.85 (edition 2024). Re-verified against stable-minus-two policy at each release.

License

Dual-licensed under MIT or Apache-2.0.

rusty-pv 0.1.0