halo

You can use halo in three different ways: manually controlling the lifecycle, using a context manager (with statement), or as a function decorator.

Manual Control

Use .start() and .stop() to manage the spinner lifecycle.

Context Manager

Use the with statement for automatic starting and stopping.

Decorator

Apply @Halo to a function to automatically show a spinner while the function executes.

Install the halo library using pip to use beautiful spinners in your terminal, IPython, or Jupyter environments.

$ pip install halo

To use spinner widgets within a Jupyter Notebook environment, import HaloNotebook from the halo package. Note that static renderers like GitHub or NBViewer may not support these widgets; you should run the notebook manually in a local Jupyter environment to see the animations.

from halo import HaloNotebook as Halo

Use the following methods on a Halo instance to control its state:

• start([text]): Starts the spinner. If text is provided, it updates the spinner text.
• stop(): Stops and clears the spinner.
• clear(): Clears the spinner.
• render(): Manually renders a new frame.
• frame(): Returns the next frame to be rendered.
• stop_and_persist([symbol|text]): Stops the spinner and replaces it with a specific symbol and/or text.

You can stop the spinner and change its symbol to indicate the outcome of a task:

• succeed([text]): Stops spinner and changes symbol to ✔.
• fail([text]): Stops spinner and changes symbol to ✖.
• warn([text]): Stops spinner and changes symbol to ⚠.
• info([text]): Stops spinner and changes symbol to ℹ.

If text is provided, it is used as the new text; otherwise, the current text is persisted.

You can update the following properties on an active Halo instance:

• spinner.text: Change the text.
• spinner.color: Change the color.
• spinner.spinner: Change the spinner animation/frames.
• spinner.enabled: Enable or disable the spinner.

Instead of using a string name for the spinner argument, you can pass a dictionary to define a custom animation. The dictionary should include an interval (in milliseconds) and a list of frames to cycle through.

spinner = Halo(
    text='Custom Spins',
    spinner={
        'interval': 100,
        'frames': ['-', '+', '*', '+', '-']
    }
)

try:
    spinner.start()
    time.sleep(2)
    spinner.succeed('It works!')
except (KeyboardInterrupt, SystemExit):
    spinner.stop()

Halo supports the context manager pattern (with statement). This ensures the spinner is handled correctly during the execution of a block. You can also capture the spinner instance using as to call methods like .succeed() within the block.

# Basic usage
with Halo(text='Loading', spinner='dots'):
    # Run time consuming work here
    time.sleep(2)

# Usage with access to the spinner instance
with Halo(text='Loading 2', spinner='dots') as spinner:
    # Run time consuming work here
    time.sleep(2)
    spinner.succeed('Done!')

You can change the text, color, and spinner type of an active spinner instance at any time to reflect changing progress or status.

spinner = Halo(text='Such Spins', spinner='dots')

try:
    spinner.start()
    time.sleep(1)
    spinner.text = 'Much Colors'
    spinner.color = 'magenta'
    time.sleep(1)
    spinner.text = 'Very emojis'
    spinner.spinner = 'hearts'
    time.sleep(1)
    spinner.stop_and_persist(symbol='🦄 '.encode('utf-8'), text='Wow!')
except (KeyboardInterrupt, SystemExit):
    spinner.stop()

You can manually control a spinner's lifecycle. Use .start() to begin the animation, .succeed() to mark a successful completion, .fail() for failures, and .stop() to terminate the spinner. You can also update the spinner's text or state mid-process by calling .start(new_text) again.

success_message = 'Loading success'
failed_message = 'Loading failed'
unicorn_message = 'Loading unicorn'

spinner = Halo(text=success_message, spinner='dots')

try:
    spinner.start()
    time.sleep(1)
    spinner.succeed()
    spinner.start(failed_message)
    time.sleep(1)
    spinner.fail()
    spinner.start(unicorn_message)
    time.sleep(1)
    spinner.stop_and_persist(symbol='🦄'.encode('utf-8'), text=unicorn_message)
except (KeyboardInterrupt, SystemExit):
    spinner.stop()