# How to Control Progress Bar Display in Semantica (Disable/Force)

> Learn how to control progress bar display in Semantica. Disable or force the console progress bar using environment variables or programmatically toggle the ProgressTracker.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-12

---

**You can disable or force the console progress bar in Semantica by setting the `SEMANTICA_DISABLE_PROGRESS=1` or `SEMANTICA_FORCE_PROGRESS=1` environment variables before the first import, or by programmatically toggling the `enabled` attribute on the singleton `ProgressTracker` instance.**

Semantica provides a configurable progress tracking system that automatically detects whether it is running in an interactive terminal or a headless environment. According to the semantica-agi/semantica source code, you can control progress bar display in Semantica through environment variables or direct API manipulation of the `ProgressTracker` class located in [`semantica/utils/progress_tracker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/progress_tracker.py).

## How the ProgressTracker Decides to Display Output

The `ProgressTracker` class (defined in [`semantica/utils/progress_tracker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/progress_tracker.py)) initializes by detecting the execution environment through internal methods like `_detect_jupyter()`, `_detect_tty()`, and `_apply_env_overrides()`. By default, it enables the console progress bar only when stdout is a terminal (TTY) and not running inside a Jupyter notebook, unless explicitly overridden.

Environment variables take precedence over automatic detection:

| Variable | Effect | Default |
|----------|--------|---------|
| **`SEMANTICA_DISABLE_PROGRESS`** | Forces the tracker to stay disabled, regardless of environment detection | `False` |
| **`SEMANTICA_FORCE_PROGRESS`** | Overrides the automatic "no-TTY" check and forces console display even when stdout is not a terminal (e.g., in CI pipelines) | `False` |

## Disabling the Progress Bar Globally

### Using the SEMANTICA_DISABLE_PROGRESS Environment Variable

To completely suppress the progress UI across all Semantica operations, set the `SEMANTICA_DISABLE_PROGRESS` environment variable before importing any Semantica modules:

```python
import os
os.environ["SEMANTICA_DISABLE_PROGRESS"] = "1"

from semantica.vector_store.vector_store import VectorStore

# The progress bar is now fully suppressed during indexing operations

```

### Programmatic Control via the Singleton

You can also disable the tracker at runtime by accessing the singleton through `get_progress_tracker()` (re-exported from [`semantica/utils/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/__init__.py)):

```python
from semantica.utils import get_progress_tracker

tracker = get_progress_tracker()
tracker.enabled = False

# Execute long-running operations without progress display

tracker.enabled = True  # Re-enable when needed

```

## Forcing the Progress Bar in Non-TTY Environments

### Enabling Display in CI Pipelines and Logs

When running Semantica in CI/CD pipelines or redirected output where stdout is not a TTY, use `SEMANTICA_FORCE_PROGRESS` to override the automatic detection:

```python
import os

os.environ["SEMANTICA_FORCE_PROGRESS"] = "1"
os.environ.pop("SEMANTICA_DISABLE_PROGRESS", None)  # Ensure disable flag is not set

from semantica.visualization.kg_visualizer import KGVisualizer

# The visualizer will now render a progress bar even without a terminal

```

## Working with the ProgressTracker API

The global `ProgressTracker` instance is managed through [`semantica/utils/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/__init__.py), which exposes `get_progress_tracker()` for module-wide access. Modules like [`semantica/vector_store/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/vector_store.py) and [`semantica/visualization/kg_visualizer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization/kg_visualizer.py) import this singleton to report operation progress.

```python
from semantica.utils import get_progress_tracker, ProgressTracker

# Access the global instance used throughout the library

tracker = get_progress_tracker()

# Create a custom tracker instance (advanced usage)

custom_tracker = ProgressTracker(enabled=False, use_emoji=False)

```

The regression tests in [`tests/test_progress_tracker_regressions.py`](https://github.com/semantica-agi/semantica/blob/main/tests/test_progress_tracker_regressions.py) verify that the environment variable logic works as expected across different execution contexts.

## Summary

- Set `SEMANTICA_DISABLE_PROGRESS=1` before import to globally suppress the progress bar in any environment.
- Set `SEMANTICA_FORCE_PROGRESS=1` to render the progress bar even when stdout is not a TTY, useful for CI/CD logs.
- Modify the `enabled` attribute on the `get_progress_tracker()` singleton for runtime control during specific operations.
- The detection logic resides in [`semantica/utils/progress_tracker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/progress_tracker.py) and handles Jupyter, TTY, and environment override checks.

## Frequently Asked Questions

### Why does the progress bar appear in Jupyter notebooks but not in my Docker logs?

By default, Semantica's `ProgressTracker` (in [`semantica/utils/progress_tracker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/progress_tracker.py)) detects Jupyter environments separately from standard TTY checks. If running in a container without a pseudo-TTY allocated, the automatic TTY detection disables the display unless you set `SEMANTICA_FORCE_PROGRESS=1`.

### Can I disable the progress bar for just one specific function call?

Yes. Because `get_progress_tracker()` returns a singleton instance, you can temporarily toggle its `enabled` attribute to `False` before the call and restore it afterward. Alternatively, set the `SEMANTICA_DISABLE_PROGRESS` environment variable only for the subprocess or context where suppression is needed.

### What takes precedence: the environment variable or the constructor argument?

According to the implementation in [`semantica/utils/progress_tracker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/progress_tracker.py), explicit constructor arguments are evaluated during initialization, but the environment variables (`SEMANTICA_DISABLE_PROGRESS`, `SEMANTICA_FORCE_PROGRESS`) are consulted in `_apply_env_overrides()` and can override automatic detection settings. Set these variables before the first import to ensure they take global effect.

### Where are the progress tracker tests located?

The regression tests verifying environment variable handling and display logic are located in [`tests/test_progress_tracker_regressions.py`](https://github.com/semantica-agi/semantica/blob/main/tests/test_progress_tracker_regressions.py) within the semantica-agi/semantica repository.