From Christoph's Personal Wiki
Jump to: navigation, search

pv (Pipe Viewer) is a terminal-based tool for monitoring the progress of data through a pipeline. It can be inserted into any normal pipeline between two processes to give a visual indication of how quickly data is passing through, how long it has taken, how near to completion it is, and an estimate of how long it will be until completion.

Additional support is available for multiple instances working in tandem, to given a visual indicator of relative throughput in a complex pipeline.

Example usage

pv allows a user to see the progress of data through a pipeline, by giving information such as time elapsed, percentage completed (with progress bar), current throughput rate, total data transferred, and ETA.

To use it, insert it in a pipeline between two processes, with the appropriate options. Its standard input will be passed through to its standard output and progress will be shown on standard error.

pv will copy each supplied FILE in turn to standard output (- means standard input), or if no FILEs are specified just standard input is copied. This is the same behaviour as cat(1).

  • A simple example to watch how quickly a file is transferred using nc(1):
$ pv file | nc -w 1 somewhere.com 3000
  • A similar example, transferring a file from another process and passing the expected size to pv:
$ cat file | pv -s 12345 | nc -w 1 somewhere.com 3000
  • A more complicated example using numeric output to feed into the dialog(1) program for a full-screen progress display:
$ (tar cf - . \
   | pv -n -s $(du -sb . | awk '{print $1}') \
   | gzip -9 > out.tgz) 2>&1 \
  | dialog --gauge 'Progress' 7 70
  • Convert a tarball from bzip2 compression to gzip:
$ pv -cN source < foobar.tar.bz2 | bzcat | pv -cN bzcat | gzip -9 | pv -cN gzip >foobar.tar.gz
  source: 7.32MB 0:00:05 [ 1.3MB/s] [===================>             ] 50% ETA 0:01:23            
    gzip: 8.96MB 0:00:05 [1.56MB/s] [         <=>                     ]
   bzcat: 45.3MB 0:00:05 [7.91MB/s] [                      <=>        ]
$ pv --help
Usage: pv [OPTION] [FILE]...
Concatenate FILE(s), or standard input, to standard output,
with monitoring.

  -p, --progress           show progress bar
  -t, --timer              show elapsed time
  -e, --eta                show estimated time of arrival (completion)
  -r, --rate               show data transfer rate counter
  -a, --average-rate       show data transfer average rate counter
  -b, --bytes              show number of bytes transferred
  -f, --force              output even if standard error is not a terminal
  -n, --numeric            output percentages, not visual information
  -q, --quiet              do not output any transfer information at all
  -c, --cursor             use cursor positioning escape sequences
  -W, --wait               display nothing until first byte transferred
  -s, --size SIZE          set estimated data size to SIZE bytes
  -l, --line-mode          count lines instead of bytes
  -i, --interval SEC       update every SEC seconds
  -w, --width WIDTH        assume terminal is WIDTH characters wide
  -H, --height HEIGHT      assume terminal is HEIGHT rows high
  -N, --name NAME          prefix visual information with NAME

  -L, --rate-limit RATE    limit transfer to RATE bytes per second
  -B, --buffer-size BYTES  use a buffer size of BYTES
  -R, --remote PID         update settings of process PID

  -h, --help               show this help and exit
  -V, --version            show version information and exit

Please report any bugs to Andrew Wood <andrew.wood@ivarch.com>.

External links