On Unix-like operating systems, the pv command displays the progress of data flowing through a pipeline.

pv was written by sysadmin and open source developer Andrew Wood.

What is pv?

The pv (“pipe viewer”) program watches data flow through a pipeline, and displays information about its progress. The information displayed by pv includes:

  • What is pv?

  • What is a pipeline?

  • Syntax

  • Examples

  • Related commands

  • Linux commands help

  • Time elapsed since data flow began.

  • Percentage complete, with progress bar.

  • Current data throughput rate.

  • Total data transferred.

  • ETA (estimated time of arrival) of when the operation is expected to be complete.

What is a pipeline?

Using the command line, you can “pipe” the output of one command to the input of another command using the vertical bar ("|"), or pipe, symbol. For example, if you want to read the contents of a text file and send it to standard output (the terminal screen), you can use the cat command:

cat myfile.txt

The ABC meeting is on Monday, October 4. The 123 conference is on Friday, August 12. The DEF meeting is on Tuesday, November 8. The GHI meeting is on Monday, December 12. …

You can use that output as input to another program. Maybe you want to extract only the lines that have the word “meeting” included. You can pipe the output to grep to filter it:

cat myfile.txt | grep meeting

The ABC meeting is on Monday, October 4. The DEF meeting is on Tuesday, November 8. The GHI meeting is on Monday, December 12.

This new output can be piped to sed to modify the output. For example, the following command extracts lines about meetings, then extracts only the lines about meetings happening on a Monday. It then extracts dates of those meetings using a Perl regular expression.

cat myfile.txt | grep meeting | grep Monday |
perl -p -e ’s/^.(?:Monday, )(.\d+).*$/$1/'

October 4 December 12

The example above shows how the output of one command can be piped to other commands in a series, called a pipeline.

In the pipeline example above, the results are shown almost instantly, so you would not need to monitor the progress. However, other commands might take a long time, and it would be helpful to know when they might finish. That is what pv is designed to do.

Syntax

The following is the general syntax of the pv command. Note that if a parameter is included with a long option name, such as –last-written NUM, the same parameter should be specified with the corresponding short option, such as -A NUM.

pv [-p | –progress] [-t | –timer] [-e | –eta] [-I | –fineta] [-r | –rate] [-a | –average-rate] [-b | –bytes] [-T | –buffer-percent] [-A | –last-written NUM] [-F | –format FORMAT] [-n | –numeric] [-W | –wait] [-D | –delay-start SEC] [-s | –size SIZE] [-l | –line-mode] [-0 | –null] [-i | –interval SEC] [-w | –width WIDTH] [-H | –height HEIGHT] [-N | –name NAME] [-f | –force] [-c | –cursor] [-L | –rate-limit RATE] [-B | –buffer-size BYTES] [-C | –no-splice] [-E | –skip-errors] [-S | –stop-at-size] [-d | –watchfd PID[:FD] [-R | –remote PID] [-P | –pidfile FILE] [file …]

pv [ -h | -V ]

Options

Display switches

The following options control how information is output by pv.

If no display switches are specified, pv behaves as if -p, -t, -e, -r, and -b were specified (everything except average rate is switched on, by default).

Output modifiers

The following options affect what information is output by pv.

Data transfer modifiers

The following options affect how data flows through the pipe being watched.

General Options

Formatting

If the -F FORMAT option is given, then the output format is determined by the FORMAT string. In that string, the following sequences can be used.

The format string equivalent of turning on all display switches is:"%N %b %T %t %r %a %p %e".

Common switches

The following are suggested common switch combinations.

Exit status

An exit status of 0 indicates successful execution with no problems.

An exit status of 1 indicates a problem with the -R or -P options. Any other exit status is a bitmask of the following:

For example, error status 26 would be a combination of error statuses 2, 8, and 16:

2 00000010 0x2 | 8 00001000 0x8 | 16 00010000 0x10 = 26 00011010 0x1a

Examples

The following examples show some ways that pv can be used in a pipeline.

Use pv like cat

pv myfile

Lorem Ipsum 12.0 B 0:00:00 [ 217KiB/s] [=========================================>] 100%

The command above reads the contents of myfile, writes them to standard output, and displays the progress.

When you provide pv with a file name, it works similar to cat, but it also displays a progress bar, byte count, throughput, etc.

Pipe to pv

cat myfile | pv

Lorem Ipsum 12.0 B 0:00:00 [ 316KiB/s] [ <=> ]

In the example above, cat reads the contents of the file and sends them to pv. This time, pv doesn’t show percent complete, because it’s reading from standard input and a size was not specified with -s. Because it doesn’t know the size of the input, it can only display the bytes transferred, time elapsed, and throughput. The progress meter only moves back and forth to indicate that data is currently being transferred.

The file contents are then sent to standard output by pv.

Test pipeline “top speed”

pv < /dev/zero > /dev/null

The command above reads from the virtual device /dev/zero that streams null characters (ASCII 0), monitors throughput, and sends output to the /dev/null virtual device. (NOTE: /dev/null points to nothing, resulting in the output being discarded.) This is a simple way to test the “top speed” of data flowing through a pipeline in your shell.

Monitor the progress of dd

The pv command can monitor the progress of dd.

For example, let’s say you’re using the dd command to create a Debian Linux installation disk. You’ve already downloaded the Debian ISO image from the official mirror site, and you want to write it to an empty USB flash drive. You have used lsblk to verify that the USB flash drive is inserted on device /dev/sda, and you have used umount or findmnt to verify that none of its partitions are currently mounted.

You can run the following command as the superuser to write the ISO file to the USB flash drive:

Be very careful when using the dd command. If you specify the wrong output device, you could overwrite data on the wrong device, including your system disk. Do not copy and run the following commands, unless you’re sure you understand what the command is doing.

dd if=debian-11.2.0-amd64-DVD-1.iso of=/dev/sda bs=4M

This operation does not display any output. When you see the shell prompt again, you know it’s complete.

In the example above, dd is run only once, handling the input (if=) and output (of=) in a single command. Alternatively, you can invoke dd twice, once for the input and once for the output, and insert pv between the two invocations, to monitor the data flow.

dd if=debian-11.2.0-amd64-DVD-1.iso | pv | dd of=/dev/sda bs=4M

In the pipeline above, the data flows like the following:

  • The first dd reads the ISO file and send the data to standard output, which is piped to pv.
  • pv monitors that data flow, displays information about it, and sends the data to the second instance of dd.
  • The second dd command reads that data as input, and writes the data to the destination device.

The benefit of this method is that the pv progress meter tells you how long until the operation is complete.

ps — Report the status of a process or processes.top — Display a sortable, continually-updated list of processes.

The version of dd included with GNU Coreutils version 8.24 and above supports the dd option status=progress. When specified, this option displays the throughput rate, time elapsed, and amount of data copied. However, the method above using pv works with any version of dd, and includes an ETA if the data size is specified with -s.