tqdm

Show iterations per second and use stdout afterwards

$ [seq 10000000] | tqdm | [command]

$ [seq 10000000] | tqdm --total [10000000] | [command]

$ zip [[-r|--recurse-paths]] [path/to/archive.zip] [path/to/directory] | tqdm --total $(find [path/to/directory] | wc [[-l|--lines]]) --unit files --null

$ tar vzcf [path/to/archive.tar.gz] [path/to/directory] 2>&1 | tqdm --total $(find [path/to/directory] | wc [[-l|--lines]]) --unit files --null

command_to_pipe_output | tqdm [options]
tqdm [options] < filename
tqdm [options] --total N --unit 'item'

--help
    Show a help message and exit, detailing all available options.

--version
    Display the tqdm program's version number and exit.

--total N
    Manually set the total number of expected iterations or units. Essential if input size cannot be inferred.

--unit UNIT
    Specify the string description of the unit (e.g., 'B' for bytes, 'it' for iterations).

--unit_scale
    Enable automatic scaling of the unit suffix (e.g., 'K', 'M', 'G' for bytes).

--bytes
    A shortcut for `--unit B --unit_scale --unit_divisor 1024`, ideal for tracking byte streams.

--desc DESC
    Add a string prefix to the progress bar, useful for identifying different progress bars.

--ascii
    Force the use of an ASCII-only progress bar, suitable for terminals that don't support Unicode characters.

--ncols N
    Set the width of the entire output line for the progress bar. Auto-detected if not specified.

--colour COLOUR
    Specify the color of the progress bar (e.g., 'red', 'green', or hex codes like '#00ff00').

--disable
    Completely disable the progress bar, useful for non-interactive scripts or when output needs to be clean.

--leave
    Keep the progress bar displayed on screen after completion, instead of clearing it.

--position N
    Specify the line offset to print the progress bar, useful for managing multiple or nested progress bars.

tqdm is a fast, extensible, and highly customizable progress bar library. Primarily developed for Python, it also offers a convenient command-line interface, making it versatile for various scripting and data processing tasks. When used via the command line, tqdm wraps around other commands, displaying a live progress bar that tracks the flow of data through a pipeline or the processing of a file. It automatically estimates remaining time, throughput, and completion percentage, providing immediate visual feedback for long-running operations. The library is designed to have minimal overhead, ensuring it doesn't significantly impede the performance of the task it's monitoring. Its name, tqdm, is derived from the Arabic word "taqaddum" (تقدّم), meaning "progress."

While powerful, tqdm's command-line interface is primarily a wrapper for its Python library. Its effectiveness depends on proper piping or explicit input (`--total`, `--file`). For extremely short-lived commands or very high iteration rates, the overhead of the progress bar might be noticeable. Additionally, tqdm outputs the progress bar to stderr by default, which can be unexpected for users assuming stdout for all output.

By design, tqdm prints the progress bar itself to the standard error stream (stderr). This allows the actual data or output from the piped command to flow through standard output (stdout) undisturbed, which is crucial for correct pipeline operation and redirection.

Beyond basic progress, tqdm offers deep customization options. Users can define custom bar formats, integrate their own metrics, and control every visual aspect from color to unit representation. This makes it highly adaptable for complex scenarios where specific information needs to be conveyed to the user about the ongoing process.

tqdm was first introduced in 2014 by Noam Yorav-Raphael, quickly becoming a popular choice for displaying progress bars in Python applications due to its simplicity and rich feature set. Its development has been community-driven, leading to continuous enhancements in performance, customizability, and display options. The command-line utility, allowing tqdm to be used directly in shell pipelines, was added later, extending its utility beyond pure Python scripts and making it accessible to a wider range of users for general data processing tasks.

pv(1), dialog(1), whiptail(1)