API Reference


class enlighten.Manager(stream=None, counter_class=Counter, **kwargs)

Manager class for outputting progress bars to streams attached to TTYs

Progress bars are displayed at the bottom of the screen with standard output displayed above.


A companion stream is a file object that shares a TTY with the primary output stream. The cursor position in the companion stream will be moved in coordination with the primary stream.

If the value is None, sys.stdout and sys.stderr will be used as companion streams. Unless explicitly specified, a stream which is not attached to a TTY (the case when redirected to a file), will not be used as a companion stream.

counter(position=None, **kwargs)

Instance of counter class

Return type:


Get a new progress bar instance

If position is specified, the counter's position can change dynamically if additional counters are called without a position argument.


Clean up and reset terminal

This method should be called when the manager and counters will no longer be needed.

Any progress bars that have leave set to True or have not been closed will remain on the console. All others will be cleared.

Manager and all counters will be disabled.

class enlighten.Counter(**kwargs)
  • bar_format (str) -- Progress bar format, see Format below
  • count (int) -- Initial count (Default: 0)
  • counter_format (str) -- Counter format, see Format below
  • desc (str) -- Description
  • enabled (bool) -- Status (Default: True)
  • leave (True) -- Leave progress bar after closing (Default: True)
  • manager (Manager) -- Manager instance. Creates instance if not specified
  • min_delta (float) -- Minimum time, in seconds, between refreshes (Default: 0.1)
  • series (sequence) -- Progression series, see Series below
  • stream (file object) -- Output stream. Not used when instantiated through a manager
  • total (int) -- Total count when complete
  • unit (str) -- Unit label

Progress bar and counter class

A Counter instance can be created with the Manager.counter() method or, when a standalone progress bar for simple applications is required, the Counter class can be called directly. The output stream will default to sys.stdout unless stream is set.


With the default values for bar_format and counter_format, floats can not be used for total, count, or provided to update(). In order to use floats, provide custom formats to bar_format and counter_format. See Format below.


The progress bar is constructed from the characters in series. series must be a sequence (str, list, tuple) containing single characters.

Default progress series (series):

' ▏▎▍▌▋▊▉█'

The first character is the fill character. When the count is 0, the bar will be made up of only this character. In the example below, characters 5 through 9 are fill characters.

The last character is the full character. When the count is equal to total, the bar will be made up of only this character. In the example below, characters 0 through 3 are fill characters.

The remaining characters are fractional characters used to more accurately represent the transition between the full and fill characters. In the example below, character 4 is a fractional character.

'45% |████▋     |'


If total is None or count becomes higher than total, the counter format will be used instead of the progress bar format.

Default counter format (counter_format):

'{desc}{desc_pad}{count:d} {unit}{unit_pad}{elapsed}, {rate:.2f}{unit_pad}{unit}/s]{fill}'

# Example output
'Loaded 30042 Files [00:01, 21446.45 Files/s]                                    '

Default progress bar format (bar_format):

'{desc}{desc_pad}{percentage:3.0f}%|{bar}| {count:{len_total}d}/{total:d} [{elapsed}<{eta}, {rate:.2f}{unit_pad}{unit}/s]'

# Example output
'Processing    22%|█████▊                   |  23/101 [00:27<01:32, 0.84 Files/s]'

Available fields:

  • count(int) - Current value of count
  • desc(str) - Value of desc
  • desc_pad(str) - A single space if desc is set, otherwise empty
  • elapsed(str) - Time elapsed since instance was created
  • rate(float) - Average increments per second since instance was created
  • unit(str) - Value of unit
  • unit_pad(str) - A single space if unit is set, otherwise empty

Addition fields for bar_format only:

  • bar(str) - Progress bar draw with characters from series
  • eta(str) - Estimated time to completion
  • len_total(int) - Length of total when converted to a string
  • percentage(float) - Percentage complete
  • total(int) - Value of total

Addition fields for counter_format only:

  • fill(str) - blank spaces, number needed to fill line

Instance Attributes


int - Current count


str - Description


float - Time since start (since last update if count`equals :py:attr:`total)


bool - Current status


Manager - Manager Instance


int - Current position


int - Total count when complete


str - Unit label

Parameters:flush (bool) -- Flush stream after clearing progress bar (Default:True)

Clear progress bar


Do final refresh and remove from manager

If leave is True, the default, the effect is the same as refresh().

format(width=None, elapsed=None)
  • width (int) -- Width in columns to make progress bar
  • elapsed (float) -- Time since started. Automatically determined if None

Formatted progress bar or counter

Return type:


Format progress bar or counter

refresh(flush=True, elapsed=None)
  • flush (bool) -- Flush stream after writing progress bar (Default:True)
  • elapsed (float) -- Time since started. Automatically determined if None

Redraw progress bar

update(incr=1, force=False)
  • incr (int) -- Amount to increment count (Default: 1)
  • force (bool) -- Force refresh even if min_delta has not been reached

Increment progress bar and redraw

Progress bar is only redrawn if min_delta seconds past since the last update


enlighten.get_manager(stream=None, counter_class=Counter, **kwargs)

Manager instance

Return type:


Convenience function to get a manager instance

If stream is not attached to a TTY, the Manager instance is disabled.