Crate indicatif

indicatif is a library for Rust that helps you build command line interfaces that report progress to users. It comes with various tools and utilities for formatting anything that indicates progress.

Platform support:

Best paired with other libraries in the family:

Crate Contents

Progress Bars and Spinners

indicatif comes with a ProgressBar type that supports both bounded progress bar uses as well as unbounded "spinner" type progress reports. Progress bars are Sync and Send objects which means that they are internally locked and can be passed from thread to thread.

Additionally a MultiProgress utility is provided that can manage rendering multiple progress bars at once (eg: from multiple threads).

To whet your appetite, this is what this can look like:

Progress bars are manually advanced and by default draw to stderr. When you are done, the progress bar can be finished either visibly (eg: the progress bar stays on the screen) or cleared (the progress bar will be removed).

use indicatif::ProgressBar;

let bar = ProgressBar::new(1000);
for _ in 0..1000 {
    bar.inc(1);
    // ...
}
bar.finish();

Spinners can be manually advanced with tick, or you can set them up to spin automatically with enable_steady_tick:

use std::time::Duration;
use indicatif::ProgressBar;

let bar = ProgressBar::new_spinner();
bar.enable_steady_tick(Duration::from_millis(100));
// ... do some work
bar.finish();

General progress bar behaviors:

Iterators

Similar to tqdm, progress bars can be associated with an iterator. For example:

use indicatif::ProgressIterator;

for _ in (0..1000).progress() {
    // ...
}

See the ProgressIterator trait for more methods to configure the number of elements in the iterator or change the progress bar style. Indicatif also has optional support for parallel iterators with Rayon. In your Cargo.toml, use the "rayon" feature:

[dependencies]
indicatif = {version = "*", features = ["rayon"]}

And then use it like this:

# extern crate rayon;
use indicatif::ParallelProgressIterator;
use rayon::iter::{ParallelIterator, IntoParallelRefIterator};

let v: Vec<_> = (0..100000).collect();
let v2: Vec<_> = v.par_iter().progress_count(v.len() as u64).map(|i| i + 1).collect();
assert_eq!(v2[0], 1);

Or if you'd like to customize the progress bar:

# extern crate rayon;
use indicatif::{ProgressBar, ParallelProgressIterator, ProgressStyle};
use rayon::iter::{ParallelIterator, IntoParallelRefIterator};

// Alternatively, use `ProgressBar::new().with_style()`
let style = ProgressStyle::default_bar();
let v: Vec<_> = (0..100000).collect();
let v2: Vec<_> = v.par_iter().progress_with_style(style).map(|i| i + 1).collect();
assert_eq!(v2[0], 1);

Templates

Progress bars can be styled with simple format strings similar to the ones in Rust itself. The format for a placeholder is {key:options} where the options part is optional. If provided the format is this:

<^>             for an optional alignment specification (left, center and right respectively)
WIDTH           an optional width as positive integer
!               an optional exclamation mark to enable truncation
.STYLE          an optional dot separated style string
/STYLE          an optional dot separated alternative style string

For the style component see Style::from_dotted_str for more information. Indicatif uses the console base crate for all colorization and formatting options.

Some examples for templates:

[{elapsed_precise}] {bar:40.cyan/blue} {pos:>7}/{len:7} {msg}

This sets a progress bar that is 40 characters wide and has cyan as primary style color and blue as alternative style color. Alternative styles are currently only used for progress bars.

Example configuration:

# use indicatif::{ProgressBar, ProgressStyle};
# let bar = ProgressBar::new(0);
bar.set_style(ProgressStyle::with_template("[{elapsed_precise}] {bar:40.cyan/blue} {pos:>7}/{len:7} {msg}")
    .unwrap()
    .progress_chars("##-"));

The following keys exist:

If the list above does not contain the value you need, consider creating a custom [ProgressTracker][crate::style::ProgressTracker] implementation.

The design of the progress bar can be altered with the integrated template functionality. The template can be set by changing a ProgressStyle and attaching it to the progress bar.

Human Readable Formatting

There are some formatting wrappers for showing elapsed time and file sizes for human users:

# use std::time::Duration;
use indicatif::{HumanBytes, HumanCount, HumanDuration, HumanFloatCount};

assert_eq!("3.00 MiB", HumanBytes(3*1024*1024).to_string());
assert_eq!("8 seconds", HumanDuration(Duration::from_secs(8)).to_string());
assert_eq!("33,857,009", HumanCount(33857009).to_string());
assert_eq!("33,857,009.1235", HumanFloatCount(33857009.123456).to_string());

Feature Flags

Modules