Progress Bar#

When executing longer-running commands, it may be helpful to show progress information, which updates as your command runs:

To display progress details, use the progress_bar() method (which returns a ProgressBar instance), pass it a total number of units, and advance the progress as the command executes:

def handle(self):
    # Create a new progress bar (50 units)
    progress = self.progress_bar(50)

    # Start and displays the progress bar
    for _ in range(50):
        # ... do some work

        # Advance the progress bar 1 unit
        progress.advance()

        # You can also advance the progress bar by more than 1 unit
        # progress.advance(3)

    # Ensure that the progress bar is at 100%
    progress.finish()

Instead of advancing the bar by a number of steps (with the advance() method), you can also set the current progress by calling the set_progress() method.

If you don't know the number of steps in advance, just omit the steps argument when using the progress_bar method:

progress = self.progress_bar()

The progress will then be displayed as a throbber:

# no max steps (displays it like a throbber)
   0 [>---------------------------]
   5 [----->----------------------]
   5 [============================]

# max steps defined
 0/3 [>---------------------------] 0%
 1/3 [=========>------------------] 33%
 3/3 [============================] 100%

Whenever your task is finished, don't forget to call finish() to ensure that the progress bar display is refreshed with a 100% completion.

Customizing the Progress Bar#

Built-in Formats#

By default, the information rendered on a progress bar depends on the current level of verbosity of the IO instance:

# Verbosity.NORMAL (CLI with no verbosity flag)
 0/3 [>---------------------------] 0%
 1/3 [=========>------------------] 33%
 3/3 [============================] 100%

# Verbosity.VERBOSE (-v)
 0/3 [>---------------------------] 0% 1 sec
 1/3 [=========>------------------] 33% 1 sec
 3/3 [============================] 100% 1 sec

# Verbosity.VERY_VERBOSE (-vv)
 0/3 [>---------------------------] 0% 1 sec
 1/3 [=========>------------------] 33% 1 sec
 3/3 [============================] 100% 1 sec

# Verbosity.DEBUG (-vvv)
 0/3 [>---------------------------] 0% 1 sec/1 sec 1.0 MB
 1/3 [=========>------------------] 33% 1 sec/1 sec 1.0 MB
 3/3 [============================] 100% 1 sec/1 sec 1.0 MB

Instead of relying on the verbosity mode of the current command, you can also force a format via set_format():

progress.set_format('verbose')

The built-in formats are the following:

• normal

• verbose

• very_verbose

• debug

If you don't set the number of steps for your progress bar, use the _nomax variants:

• normal_nomax

• verbose_nomax

• very_verbose_nomax

• debug_nomax

Custom Formats#

Instead of using the built-in formats, you can also set your own:

progress.set_format('%bar%')

This sets the format to only display the progress bar itself:

>---------------------------
=========>------------------
============================

A progress bar format is a string that contains specific placeholders (a name enclosed with the % character); the placeholders are replaced based on the current progress of the bar. Here is a list of the built-in placeholders:

• current: The current step

• max: The maximum number of steps (or 0 if no max is defined)

• bar: The bar itself

• percent: The percentage of completion (not available if no max is defined)

• elapsed: The time elapsed since the start of the progress bar

• remaining: The remaining time to complete the task (not available if no max is defined)

• estimated: The estimated time to complete the task (not available if no max is defined)

• memory: The current memory usage

• message: The current message attached to the progress bar

For instance, here is how you could set the format to be the same as the debug one:

progress.set_format(' %current%/%max% [%bar%] %percent:3s%% %elapsed:6s%/%estimated:-6s% %memory:6s%')

Notice the :6s part added to some placeholders? That's how you can tweak the appearance of the bar (formatting and alignment). The part after the colon (:) is used to set the format of the string.

The message placeholder is a bit special as you must set the value yourself:

progress.set_message('Task starts')
progress.start()

progress.set_message('Task in progress...')
progress.advance()

# ...

progress.set_message('Task is finished')
progress.finish()

Bar Settings#

Amongst the placeholders, bar is a bit special as all the characters used to display it can be customized:

# the finished part of the bar
progress.set_bar_character('<comment>=</comment>')

# the unfinished part of the bar
progress.set_empty_bar_character(' ')

# the progress character
progress.set_progress_character('|')

# the bar width
progress.set_bar_width(50)