LinuxCommandLibrary

pv

Monitor data progress through a pipe

TLDR

Print the contents of the file and display a progress bar

$ pv [path/to/file]
copy

Measure the speed and amount of data flow between pipes (--size is optional)
$ command1 | pv [[-s|--size]] [expected_amount_of_data_for_eta] | command2
copy

Filter a file, see both progress and amount of output data
$ pv [[-cN|--cursor --name]] in [big_text_file] | grep [pattern] | pv [[-cN|--cursor --name]] out > [filtered_file]
copy

Attach to an already running process and see its file reading progress
$ pv [[-d|--watchfd]] [PID]
copy

Read an erroneous file, skip errors as dd conv=sync,noerror would
$ pv [[-EE|--skip-errors --skip-errors]] [path/to/faulty_media] > image.img
copy

Stop reading after reading specified amount of data, rate limit to 1K/s
$ pv [[-L|--rate-limit]] 1K [[-S|--stop-at-size]] [maximum_file_size_to_be_read]
copy

SYNOPSIS

pv [options] [file]

PARAMETERS

-p, --progress
    Show a progress bar indicating how much data has been transferred.

-t, --timer
    Show a running timer displaying how long pv has been running.

-e, --eta
    Show an estimated time of arrival (ETA), based on current transfer rate.

-r, --rate
    Show the current rate of data transfer (bytes per second).

-b, --bytes
    Show the total number of bytes transferred.

-T, --null
    Do not display any output. Useful for delaying data streams.

-A, --average-rate
    Show the average rate of data transfer over the entire transfer.

-n, --numeric
    Only output numbers, not human-readable units.

-W, --wait
    Wait until the first byte has been transferred before showing any output.

-f, --force
    Force operation even if standard input is not a pipe. Potentially dangerous.

-q, --quiet
    Do not output any transfer information to standard error.

-s SIZE, --size SIZE
    Assume SIZE total bytes to be transferred.

-L RATE, --rate-limit RATE
    Limit the transfer to a maximum of RATE bytes per second.

-d NUMBER, --delay-start NUMBER
    Delay at start before showing output, default unit is seconds.

-N NAME, --name NAME
    Prefix the output information with NAME.

-c, --cursor
    Use cursor positioning to overwrite the output rather than scrolling.

-w WIDTH, --width WIDTH
    Assume the terminal is WIDTH characters wide.

-H, --help
    Display help text and exit.

-V, --version
    Output version information and exit.

DESCRIPTION

The pv command is a terminal-based tool for monitoring the progress of data as it's piped through a sequence of commands. Think of it as a 'pipe viewer'. It provides real-time information such as the rate of data transfer, elapsed time, percentage completed, and a progress bar. pv is commonly used when transferring large files, backing up data, or performing other tasks where you want to know how quickly the operation is progressing. It sits unobtrusively between any two commands connected by a pipe, offering valuable insight into the data flow without altering the data itself.
pv can also be used to add artificial delays to data streams. It's a versatile tool for anyone working with data streams in a Linux or Unix-like environment.

CAVEATS

pv relies on being able to determine the size of the data being transferred for accurate progress estimation. If the size is unknown (e.g., piping from a command that doesn't provide size information), the progress bar and ETA may be inaccurate or unavailable.
Using pv might slightly slow down the overall operation due to the overhead of monitoring and displaying data.

EXAMPLES

  • Monitor `tar` command:
    tar cf - . | pv | gzip > archive.tgz

  • Limit transfer rate:
    pv -L 1m input.img > output.img (Limits transfer to 1MB/s)

SEE ALSO

dd(1), cat(1), gzip(1), tar(1)

Copied to clipboard