Pipe Viewer - monitor the progress of data through a pipe


This is the README for `pv' ("Pipe Viewer"), 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.


A manual page is included in this distribution.  See `man ./doc/quickref.1',
or `man pv' after installation.


If this is not a packaged release, first run "./generate.sh".

To compile the package, type "sh ./configure", which should generate a
Makefile for your system.  You may then type "make" to build everything.
Note that GNU `make' is required; this may be installed as `gmake' on some
systems, so if typing "make" gives an error, try "gmake" instead.

See the file `doc/INSTALL' for more about the `configure' script.

Developers note that you can do "./configure --enable-debugging" to cause
debugging support to be built in, and "--enable-profiling" builds in
profiling support (see "man gprof").  Also note that doing "make index" will
generate an HTML code index (using "ctags" and "cproto"); this index lists
all files used, all functions defined, and all TODOs marked in the code.

Author and acknowledgements

This package is copyright 2021 Andrew Wood, and is being distributed under
the terms of the Artistic License 2.0.  For more details of this license,
see the file `doc/COPYING'.

Report bugs in `pv' using the contact form linked from the home page.

The `pv' home page is at:


The latest version can always be found here.

Credit is also due to:

  Jakub Hrozek <[email protected]>
    - Fedora package maintainer

  Antoine Beaupré <[email protected]>
    - Debian package maintainer

  Kevin Coyner <[email protected]>
  Cédric Delfosse <[email protected]>
    - previous Debian package maintainers

  Eduardo Aguiar <[email protected]>
    - provided Portuguese (Brazilian) translation

  Stéphane Lacasse <[email protected]>
    - provided French translation

  Marcos Kreinacke <[email protected]>
    - provided German translation

  Bartosz Feñski <[email protected]> <http://skawina.eu.org/>
    - provided Polish translation along with Krystian Zubel

  Joshua Jensen
    - reported RPM installation bug

  Boris Folgmann <http://www.folgmann.com/en/>
    - reported cursor handling bug

  Mathias Gumz
    - reported NLS bug

  Daniel Roethlisberger
    - submitted patch to use lockfiles for -c if terminal locking fails

  Adam Buchbinder
    - lots of help with a Cygwin port of -c

  Mark Tomich <http://metuchen.dyndns.org>
    - suggested -B option

  Gert Menke
    - reported bug when piping to dd with a large input buffer size

  Ville Herva <[email protected]>
    - informative bug report about rate limiting performance

  Elias Pipping
    - patch to compile properly on Darwin 9; potential NULL deref report

  Patrick Collison
    - similar patch for OS X

  Boris Lohner
    - reported problem that "-L" does not complain if given non-numeric value

  Sebastian Kayser
    - supplied testing for SIGPIPE, demonstrated internationalisation problem

  Laszlo Ersek <http://phptest11.atw.hu/>
    - reported shared memory leak on SIGINT with -c

  Phil Rutschman <http://bandgap.rsnsoft.com/>
    - provided a patch for fully restoring terminal state on exit

  Henry Precheur <http://henry.precheur.org/>
    - reporting and suggestions for --rate-limit bug when rate is under 10

  E. Rosten <http://mi.eng.cam.ac.uk/~er258/>
    - supplied patch for block buffering in line mode

  Kjetil Torgrim Homme
    - reported compilation error with default CFLAGS on non-GCC compilers

  Alexandre de Verteuil
    - reported bug in OS X build and supplied test environment to fix in

  Martin Baum
    - supplied patch to return nonzero exit status if terminated by signal

  Sam Nelson <http://www.siliconfuture.net/>
    - supplied patch to fix trailing slash on DESTDIR

  Daniel Pape
    - reported Cygwin installation problem due to DESTDIR

  Philipp Beckers
    - ported to the Syabas PopcornHour A-100 series

  Henry Gebhard <[email protected]>
    - supplied patches to improve SI prefixes and add --average-rate

  Vladimir Kokarev, Alexander Leo
    - reported that exit status did not reflect file errors

  Thomas Rachel
    - submitted patches for IEEE1541 (MiB suffixes), 1+e03 bug

  Guillaume Marcais
    - submitted speedup patch for line mode

  Moritz Barsnick
    - submitted patch for compile warning in size calculation

  Pawel Piatek
    - submitted RPM and patches for AIX

  Sami Liedes
    - submitted patch for --timer and --bytes with --numeric

  Steven Willis
    - reported problem with "-R" killing non-PV remote processes

  Vladimir Pal, Vladimir Ermakov
    - submitted patch which led to development of --format option

  Peter Samuelson <[email protected]>
    - submitted patch to calculate size if stdout is a block device

  Miguel Diaz
    - much Cygwin help (and packaging), found narrow-terminal bug

  Jim Salter <http://ubuntuwiki.net>
    - commissioned work on the --skip-errors option

  Wouter Pronk
    - reported build problem on SCO

  Bryan Dongray <http://www.dongrays.com>
    - provided patches for test scripts failing on older Red Hats

  Zev Weiss <www.bewilderbeest.net>
    - provided patch to fix splice() not using stdin

  Zing Shishak
    - provided patch for --null / -0 (count null terminated lines)

  Jacek Wielemborek <http://deetah.jogger.pl/kategorie/english>
    - implemented fdwatch in Python, suggested PV port
    - reported bug with "-l" and ETA / size
    - suggested common switches

  Kim Krecht
    - suggested buffer fill status and last bytes output display options

  Cristian Ciupitu <http://ciupicri.github.io>, Josh Stone
    - pointed out file descriptor leak with helpful suggestions
      (Josh Stone initially noticed the missing close)

  Jan Seda
    - found issue with splice() and SPLICE_F_NONBLOCK causing slowdown

  André Stapf
    - pointed out formatting problem e.g. 13GB -> 13.1GB which should be
      shown 13.0GB -> 13.1GB; highlighted on-startup row swapping in -c

  Damon Harper <http://www.usrbin.ca/>
    - suggested "-D" / "--delay-start" option

  Ganaël Laplanche <http://www.martymac.org>
    - provided patch for lstat64 on systems that do not support it

  Peter Korsgaard <http://www.buildroot.net/>
    - provided similar patch for lstat64, specifically for uClibc support
    - provided AIX cross-compilation patch to fix bug in -lc128 check

  Ralf Ramsauer <https://blog.ramses-pyramidenbau.de/>
    - reported bug which dropped transfer rate on terminal resize

  Michiel Van Herwegen
    - reported and discussed bug with "-l" and ETA / size

  Erkki Seppälä <http://www.inside.org/~flux/>
    - provided patch implementing "-I"

  Eric A. Borisch
    - provided details of compatibility fix for "%Lu" in watchpid code

  Jan Venekamp
    - reported MacOS buffer size interactions with pipes

  Matt <https://github.com/lemonsqueeze/pv>
    - provided "rate-window" patches for rate calculation

  Filippo Valsorda
    - provided patch for stat64 issue on Apple Silicon

  Matt Koscica, William Dillon
    - also reported stat64 issue on Apple Silicon

  Norman Rasmussen
    - suggested -c with -d PID:FD, reject -N with -d PID

  Andriy Gapon, Jonathan Elchison
    - reported bug where "pv /dev/zero >/dev/null &" stops immediately

  Marcelo Chiesa
    - reported unused-result warnings when compiling PV 1.6.6

  Jered Floyd
    - provided patches to improve --rate-limit

  Christoph Biedl
    - provided ETA and dynamic interval patches

  Richard Fonfara
    - provided German translations for "pv --help"

  Johannes Gerer <http://johannesgerer.com>
    - suggested that "-B" should enable "-C"

  Sam James
    - provided fix for number.c build issue caused by missing stddef.h

  • Adjustable averaging window for rate display

    Adjustable averaging window for rate display

    From https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=507682 in 2014 - Anthony DeRobertis [email protected]

    Package: pv Version: 1.1.4-1 Severity: wishlist File: /usr/bin/pv

    It appears that pv always averages the transfer rate over the display interval. It'd be nice if that could be controlled seperately. Right now, if you have very bursty data (for example, lzcat receiving compressed data from the network, writing uncompressed to disk), you have to use a very long update interval, on the order of a minute, to get a reasonable rate estimate. It'd be nice to keep the 1s update interval, but take the average over a longer period.

    It'd be awesome if pv recognized bursty data and adjusted the averaging itself, but that's way more than I expect.

    -- System Information: Debian Release: lenny/sid APT prefers testing APT policy: (500, 'testing'), (100, 'unstable') Architecture: i386 (i686)

    Kernel: Linux 2.6.26-1-686 (SMP w/2 CPU cores) Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8) Shell: /bin/sh linked to /bin/bash

    Versions of packages pv depends on: ii libc6 2.7-16 GNU C Library: Shared libraries

    pv recommends no packages.

    Versions of packages pv suggests: ii doc-base 0.8.16 utilities to manage online documen

    -- no debconf information

    opened by a-j-wood 2
  • src/pv/number.c: add missing <stddef.h> include for NULL

    src/pv/number.c: add missing include for NULL

    Fixes a build failure like this:

    x86_64-pc-linux-gnu-gcc -O2 -pipe -march=native -fdiagnostics-color=always -frecord-gcc-switches -I./src/include -Isrc/include -DHAVE_CONFIG_H -DLOCALEDIR=\"/usr/share/locale\" -c -o src/pv/number.o src/pv/number.c
    x86_64-pc-linux-gnu-gcc -O2 -pipe -march=native -fdiagnostics-color=always -frecord-gcc-switches -I./src/include -Isrc/include -DHAVE_CONFIG_H -DLOCALEDIR=\"/usr/share/locale\" -c -o src/pv/signal.o src/pv/signal.c
    x86_64-pc-linux-gnu-gcc -O2 -pipe -march=native -fdiagnostics-color=always -frecord-gcc-switches -I./src/include -Isrc/include -DHAVE_CONFIG_H -DLOCALEDIR=\"/usr/share/locale\" -c -o src/pv/state.o src/pv/state.c
    src/pv/number.c: In function ‘pv_getnum_ull’:
    src/pv/number.c:32:13: error: ‘NULL’ undeclared (first use in this function)
       32 |         if (NULL == str)
          |             ^~~~
    src/pv/number.c:9:1: note: ‘NULL’ is defined in header ‘<stddef.h>’; did you forget to ‘#include <stddef.h>’?
        8 | #include "pv.h"
      +++ |+#include <stddef.h>
        9 |
    src/pv/number.c:32:13: note: each undeclared identifier is reported only once for each function it appears in
       32 |         if (NULL == str)
          |             ^~~~
    src/pv/number.c: In function ‘pv_getnum_d’:
    src/pv/number.c:122:13: error: ‘NULL’ undeclared (first use in this function)
      122 |         if (NULL == str)
          |             ^~~~
    src/pv/number.c:122:13: note: ‘NULL’ is defined in header ‘<stddef.h>’; did you forget to ‘#include <stddef.h>’?
    make: *** [Makefile:362: src/pv/number.o] Error 1
    make: *** Waiting for unfinished jobs....
    src/pv/loop.c: In function ‘pv_main_loop’:


    opened by thesamesam 2
  • Provides options that display `-b` counter in exact number of bytes

    Provides options that display `-b` counter in exact number of bytes

    Hello, it looks like the current implementation of pv always display the total xfered (-b/%b) bytes in human friendly form, sometimes this is inconvenient when debugging a shell script with non-interactive pv usage (e.g. -qSs)


    I tried with dd and curl as potential alternatives but also not ideal:

    • the GNU implementation of dd seemingly doesn't print a N bytes copied line if of= is closed earlier than if= (common in SIGPIPE errs), I think this design is due to POSIX's write() does not report partial successfully written bytes on errors.
    • curl -qgsfw "%{stderr}%{size_download}" file:///dev/urandom | pv -qSs 512400 >/dev/null where curl seems does not always print actually written bytes in case of SIGPIPE (similar reason as dd below), hence wont useful for this setup.

    pv is the only program in my knowledge that utilize splice() for streaming data in given length, could you please consider to implement a option that print these values in exact number of bytes to ease diagnosing of such kinds of shell scripts?

    opened by flosnvjx 1
  • Add -s @FILENAME for specifying size

    Add -s @FILENAME for specifying size

    Intended to address Issue #44 to allow pv -s @filename like curl(1).

    Also fixes compilation on latest OSX on Apple Silicon where stat64() and friends are linkable but not compilable.

    opened by dajobe 0
  • Support for backgrounding pv, and allowing it to be monitored separately

    Support for backgrounding pv, and allowing it to be monitored separately

    I would like to be able to use pv to monitor a background transfer and periodically check the current progress. At a glance, a combination of pv -q & and pv -R $! seems like it should do the job but fails on two accounts:

    1. pv -q & immediately stops, as it wants access to the terminal (even with -q)
    2. pv -R ... affects the behaviour of the first pv in its terminal, rather than showing the progress in the current terminal

    (1) is demonstrable -- just running pv -q </dev/zero >/dev/null & ends up with a stopped job that only works when forgrounded with fg (2) is demonstrable with help from screen or tmux -- running pv -q </dev/zero >/dev/null (no &) in one window and then running pv -R $(pidof -s pv) in a second does not display anything in the second window; while running pv -R $(pidof -s pv) -p starts writing output in the first window.

    pv -d $(pidof pv) does not appear to help, I assume because the first pv already has the files open, so never "sees" a new open "event". Likewise pv -d "$(pidof pv):0" doesn't work, because the first pv has opened devices, not files (I am really hoping to monitor transfer between non-files, specifically stdout-to-fifo). I've also tried dd ... &; pv -d $(pidof dd), which suffers the same.

    I suppose both pv -R and pv -d would also be limited to only having state information about the transfer since the second pv started, and would not have access to the time/byte-count/avg-rate of the running first pv.

    As such, my enhancement request is twofold:

    1. ability to background a pv without it stopping for terminal access
    2. a specific switch, e.g. -M <pid>, to monitor (or mirror) the existing pv process indicated by <pid>, e.g by instructing the first process to IPC its transfer history to the second, and for the second to output to the terminal.
      • if a fifo-driven --redir-to / --redir-from semantic makes more sense than some other IPC, that would be fine

    Note that I am not just hoping to solve the issue of backgrounding and checking in the same session -- I would hope/expect that implementing (1) would just allow CTRL+Z and judicious use of fg/bg for that purpose. I am also looking to have pv invoked somewhere else (e.g. by cron) and be able to attach to it for occasional progress updates by an operator. It just so happens that I need a long-running-writer | pv > /tmp/fifo & behaviour, so that something else can read the fifo.

    (If any of this exists in the releases after 1.6.0, please advise/accept my apologies for the noise!)

    opened by jimbobmcgee 1
  • pv Stopped Working in the Background

    pv Stopped Working in the Background

    I have an application that starts a background pv process to generate a progress bar for a complex pipeline. This used to work as I expected in pv 1.6.6. It no longer works in pv 1.6.20. pv runs, but the progress bar is not displayed.

    In the new routine pv_in_foreground(void), the code does not check for an error return from tcgetpgrp(STDERR_FILENO).

    our_process_group = getpgrp(); 
    tty_process_group = tcgetpgrp(STDERR_FILENO);                                                                                                             
    if (our_process_group == tty_process_group)                                                                                                               
        return true; 

    Changing the code to the following does what I want:

    our_process_group = getpgrp();
    tty_process_group = tcgetpgrp(STDERR_FILENO);   
    if (tty_process_group == -1)
        return true;
    if (our_process_group == tty_process_group)                                                                                                               
        return true; 

    Alternatively, a command line flag to force pv_in_foreground() to always return true would be helpful.

    opened by CraigMiloRogers 0
  • Feature Request: Run command every n percent

    Feature Request: Run command every n percent


    pv is awesome and I'm using it for diagnostics and other purposes. Thanks for making it!

    There's one idea I've been thinking about. What about the ability to run commands at certain percentages? Perferably with formatting support. This would useful for long-running transfers that you can't/don't want to observe, but still want to be able to get pv's stats.

    e.g. something like pv --command="notify-send 'pv' '%p'" --command-interval 25 foo > bar would show a notification for every 25 percent to completion. Or --command="echo -ne '\a'" --command-interval 10 would ring the terminal bell every 10 percent.

    Cheers! :)

    opened by haarp 0
  • Strange race condition that affects `--wait` (feel free to change this title to be more descriptive)

    Strange race condition that affects `--wait` (feel free to change this title to be more descriptive)

    pv seems to have a race condition that’s triggered intermittently. Take the following script:

    # File name: bug-repro.sh
    progress() {
      # Perform some relevant calculations that may take a few millis,
      # such as calculating total size of files passed to this function.
      declare -r num_blocks="$(du -Ac "$@" | tail -1 | cut -f1)"
      declare -r bytes_per_block=512
      declare -r size_in_bytes="$(( num_blocks * bytes_per_block ))"
      # For purposes of reproducing this bug: If the above calculations
      # weren't slow enough to introduce the race condition, let's simulate
      # some more operations before calling `pv`.
      for i in {1..100}; do
      # Now call `pv` using the `--wait` switch
      pv --wait -s "${size_in_bytes}"
    tar -cf - "$@" | progress "$@" | gpg -c > /dev/null

    If I run it via $ ./bug-repro.sh file1 file2 file3, I expect that pv will wait for some bytes before displaying its progress bar, since --wait was used.

    Instead, I see this before I start entering a password for GPG:

    Enter passphrase: 64.0KiB 0:00:01 [62.2KiB/s] [===>                             64.0KiB 0:00:04 [0.00 B/s] [===>                               ] 13% ETA 0:00:25

    Interestingly, if I hard-code the -s size, pv waits as expected:

    # This behaves as expected
    tar -cf - "$@" | pv --wait -s 12345 | gpg -c > /dev/null

    Note, it may be necessary to have the following GPG configuration to successfully repro this:

    $ head ~/.gnupg/{gpg,gpg-agent}.conf
    ==> /Users/danielyli/.gnupg/gpg.conf <==
    pinentry-mode loopback
    ==> /Users/danielyli/.gnupg/gpg-agent.conf <==
    opened by danielyli 0
  • remote-cksum test failed on Fedora ppc64le

    remote-cksum test failed on Fedora ppc64le

    remote-cksum test failed on Fedora 37/rawhide ppc64le. Tests are good on other architectures.

    + make test
    sh ./autoconf/scripts/run-test.sh ./pv .
    000 - cat:             OK
    001 - interval:        OK
    002 - rate:            OK
    003 - progress:        OK
    004 - timer:           OK
    005a - eta:            OK
    005b - fineta:         OK
    006 - ratecount:       OK
    007 - bytes:           OK
    008 - numeric:         OK
    009 - quiet:           OK
    010 - pipe:            OK
    011 - cksum:           OK
    012 - averagerate:     OK
    013 - 1mboundary:      OK
    014 - 1mboundary2:     OK
    015 - cksumpipe:       OK
    016 - numeric-timer:   OK
    017 - numeric-bytes:   OK
    018 - remote-format:   OK
    019 - remote-cksum:    pv: 2411631: message not received
    020 - stop-at-size:    OK
    make: *** [Makefile:277: test] Error 1

    full log: build.log

    opened by cheese 5
btop++ - A monitor of resources

btop++ - A monitor of resources

null 9.9k Dec 31, 2022
timg - Terminal Image and Video Viewer

timg - Terminal Image and Video Viewer

Henner Zeller 1.3k Dec 31, 2022
X terminal emulator rendering through OpenGL ES Compute Shaders

Zutty is a terminal emulator for the X Window System, functionally similar to several other X terminal emulators such as xterm, rxvt and countless others

Tom Szilagyi 259 Dec 24, 2022
Screens options data to find the best options to sell for theta-gangers

Robinhood-options-screener Screens options data to find the best options to sell for theta-gangers, works for cash-secured-puts and covered-calls. Get

null 27 Nov 25, 2022
Simple command line utilities for extracting data from Fallout 4 and 76 files

fo76utils Simple command line utilities for extracting data from Fallout 4 and 76 files. baunpack - list the contents of, or extract from .BA2 archive

null 15 Dec 6, 2022
CLIp is a clipboard emulator for a command line interface written in 100% standard C only. Pipe to it to copy, pipe from it to paste.

CLIp v2 About CLIp is a powerful yet easy to use and minimal clipboard manager for a command line environment, with no dependencies or bloat. Usage Sy

A.P. Jo. 12 Sep 18, 2021
Serial Data Monitor is a multiplatform (Windows, Linux, Mac, ...) tool to interactively receive/edit/monitor data and send commands to an embedded system via the serial bus

See wiki for full documentation Serial Data Monitor Description Serial Data Monitor is a multiplatform (Windows, Linux, Mac, ...) tool to interactivel

monnoliv 4 Oct 29, 2021
✔️The smallest header-only GUI library(4 KLOC) for all platforms

Welcome to GUI-lite The smallest header-only GUI library (4 KLOC) for all platforms. 中文 Lightweight ✂️ Small: 4,000+ lines of C++ code, zero dependenc

null 6.6k Jan 8, 2023
An easy to build CO2 Monitor/Meter with Android and iOS App for real time visualization and charting of air data, data logger, a variety of communication options (BLE, WIFI, MQTT, ESP-Now) and many supported sensors.

CO2-Gadget An easy to build CO2 Monitor/Meter with cell phone App for real time visualization and charting of air data, datalogger, a variety of commu

Mariete 30 Dec 17, 2022
Samir Teymurov 1 Oct 6, 2021
Spatial extrapolation algorithm: calculate the data of other regions through the data of known regions.

Spatial interpolation Author : csl E-Mail : [email protected] OverView Spatial interpolation is often used to convert the measured data of discrete po

null 1 Oct 18, 2021
GrandOrgue is a sample based pipe organ simulator.

GrandOrgue is a sample based pipe organ simulator. It currently supports Linux, Windows and OS X. Porting to other OS supported by RtMidi,

GrandOrgue 85 Dec 31, 2022
Windows named pipe server that forwards connections to given TCP server

PipeTcp An asynchronous Windows named pipe server that forwards connections to given TCP server. Pre-built binaries can be found in Releases. Invocati

Jinoh Kang 5 Nov 3, 2022
Exploit for Dirty-Pipe (CVE-2022-0847)

Dirty-Pipe (PoC) What is it? Dirty-Pipe is a vulnerability which allows us to overwrite files even if they have read-only permissions. This vulnerabil

Nekox 7 Dec 25, 2022
A DC power monitor and data logger

Hoverboard Power Monitor I wanted to gain a better understanding of the power consumption of my hoverboard during different riding situations. For tha

Niklas Roy 22 May 1, 2021
A handy little system information monitor using and ESP32 + ILI9488 TFT. Receives data over Serial Bluetooth.

Bluetooth-System-Monitor A handy little system information monitor using and ESP32 + ILI9488 TFT. Receives data over Serial Bluetooth and thus giving

Dustin Watts 32 Dec 22, 2022
Polyscope is a C++/Python viewer and user interface for 3D data such as meshes and point clouds

Polyscope is a C++/Python viewer and user interface for 3D data such as meshes and point clouds. It allows you to register your data and quickly generate informative and beautiful visualizations, either programmatically or via a dynamic GUI.

Nicholas Sharp 1.3k Dec 30, 2022
A library to simplify the process of getting and storing data to Antares IoT Platform through HTTP on ESP8266.

Antares ESP8266 HTTP This is the documentation for Antares ESP8266 library. This library is meant to simplify the process of retrieving and deploying

null 6 Jul 2, 2021
A library to simplify the process of subscribing and publishing data to Antares IoT Platform through MQTT on ESP8266.

Antares ESP8266 MQTT A Library to simplify the process of MQTT publication and subscription to Antares IoT Platform using ESP8266. This library works

null 6 Mar 9, 2022
An easy-to-use C library for displaying text progress bars.

What is this thing? progressbar is a C-class (it's a convention, dammit) for displaying attractive progress bars on the command line. It's heavily inf

Trevor Fountain 440 Dec 27, 2022