Yet Another Terminal Spinner

3.4.0 · active · verified Thu Apr 09

yaspin is a Python library that provides a simple and flexible way to display terminal spinners for CLI applications, indicating ongoing operations. It is currently at version 3.4.0 and maintains a regular release cadence, often updating with new features, dependency bumps, and Python version support.

Warnings

breaking Python 3.8 and 3.9 support has been dropped in recent major versions. Yaspin v3.0.0 dropped Python 3.8, and v3.4.0 dropped Python 3.9. Ensure your environment uses Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10 or a later supported version (3.10, 3.11, 3.12, 3.13, 3.14 are supported by v3.4.0).
breaking Version 3.0.0 introduced significant breaking changes, including the removal of previously exposed modules (base_spinner, helpers, signal_handlers) and constants (constants.COLOR_MAP).
Fix: Review the official documentation for v3.0.0+ for updated API usage. Direct imports from these internal modules or reliance on COLOR_MAP will no longer work.
deprecated The `is_jupyter()` method has been deprecated.
Fix: Avoid using `is_jupyter()`. If you need to detect a Jupyter environment, consider alternative methods or check the yaspin documentation for recommended practices.
gotcha While yaspin aims for 'pipe safety', early versions and certain terminal environments (especially on Windows) might exhibit issues where spinner control characters are visible when piping output to files or other programs.
Fix: If encountering unwanted control characters in piped output, ensure you are on a recent `yaspin` version and consider using `sys.stdout.isatty()` checks in your code to conditionally disable `yaspin` or redirect its output to `sys.stderr` when `stdout` is not a TTY.
gotcha Integrating yaspin with complex multithreaded applications might require careful synchronization to prevent display glitches or unexpected behavior, as multiple threads writing to the console can interfere with the spinner's output.
Fix: If using yaspin in a multithreaded context, ensure that other threads do not write directly to `sys.stdout` while the spinner is active, or use `yaspin.write()` for thread-safe output. Consider using a `threading.Lock` to manage console access if conflicts arise.

Install

pip install yaspin Install latest version

Imports

yaspin
```
from yaspin import yaspin
```
Spinner
```
from yaspin import Spinner
```
Used for creating custom spinners with specific frames and intervals.

Quickstart

The most common way to use yaspin is as a context manager, wrapping your time-consuming operations. You can customize the spinner type, text, and colors, and then finalize with success or failure indicators.

import time
from yaspin import yaspin

# Basic usage as a context manager
with yaspin(text="Processing...") as sp:
    time.sleep(2) # Simulate work
    sp.ok("✔") # Mark as success

# Example with custom spinner and colors
from yaspin.spinners import Spinners

with yaspin(Spinners.earth, text="Loading data...").white.on_blue as sp:
    time.sleep(3)
    if time.time() % 2 == 0: # Simulate a random outcome
        sp.fail("✘") # Mark as failure
    else:
        sp.ok("✨") # Mark with a sparkle

view raw JSON →