📊 Visualizzare grafici nel terminale con termgraph usando Python

termgraph è una libreria Python pensata per rappresentare dati numerici direttamente nel terminale, senza dipendenze grafiche esterne. A differenza di librerie come matplotlib, termgraph produce output testuale strutturato, ideale per script, tool CLI e ambienti headless.

In questo articolo vedremo soprattutto l’uso programmatico della libreria, sfruttando le classi esposte dall’API Python. Infine faremo un accenno all'utlizzo della libreria da command line (cli).

🔗 Ti piace Techelopment? Dai un'occhiata al sito per tutti i dettagli!

Installazione

pip install termgraph

Concetti base dell’API Python

L’API Python di termgraph ruota attorno a tre componenti principali:

Data → contiene valori e label
Args → configurazione del grafico (larghezza, titolo, formato, colori, ecc.)
BarChart / StackedBarChart / CalendarHeatmap → oggetti che disegnano il grafico

Esempio 1 — Grafico a barre semplice

Il grafico a barre è il caso d’uso più comune.

from termgraph import Data, Args, BarChart

values = [[10], [20], [35], [50]]
labels = ["A", "B", "C", "D"]

data = Data(values, labels)

args = Args(
    title="Esempio grafico a barre",
    width=40,
    format="{:.0f}"
)

chart = BarChart(data, args)
chart.draw()

Output

Esempio 2 — Grafico a barre con più serie

termgraph supporta più serie di dati per ogni etichetta.

from termgraph import Data, Args, BarChart

values = [
    [10, 20],
    [15, 25],
    [30, 10],
]

labels = ["Gennaio", "Febbraio", "Marzo"]

data = Data(values, labels)

args = Args(
    title="Vendite prodotto A e B",
    width=50,
    format="{:.0f}"
)

chart = BarChart(data, args)
chart.draw()

Output

Esempio 3 — Formattazione dei valori e suffisso

È possibile personalizzare il formato numerico e aggiungere un suffisso (ad esempio “K”, “MB”, “%”).

from termgraph import Data, Args, BarChart

data = Data(
    [[1200], [3400], [2900]],
    ["Server 1", "Server 2", "Server 3"]
)

args = Args(
    title="Utilizzo memoria",
    width=45,
    format="{:.1f}",
    suffix=" MB"
)

chart = BarChart(data, args)
chart.draw()

Output

Esempio 4 — Barre colorate

termgraph supporta i colori ANSI per distinguere le serie.

from termgraph import Data, Args, BarChart, Colors

data = Data(
    data=[[5, 8], [3, 6], [7, 2]],
    labels=["Task 1", "Task 2", "Task 3"]
)

args = Args(
    title="Durata task",
    width=40,
    colors=[Colors.Cyan, Colors.Blue]
)

chart = BarChart(data, args)
chart.draw()

Output

Esempio 5 — Grafico a barre impilate (stacked)

Quando i valori rappresentano parti di un totale, il grafico impilato è molto utile.

from termgraph import Data, Args, StackedBarChart

data = Data(
    [[3, 2, 1], [4, 1, 2]],
    ["Servizio A", "Servizio B"]
)

args = Args(
    title="Distribuzione risorse",
    width=50,
    color=["green", "magenta", "cyan"],
    labels=["CPU", "RAM", "IO"]
)

chart = StackedBarChart(data, args)
chart.draw()

Output

Esempio 6 — Grafico a barre verticali

Purtroppo termgraph dichiara il supporto ai grafici a barre verticali ma il codice fornito sul sito ufficiale del progetto github non funziona benissimo...

Questo è il risultato dopo aver fixato la dichiarazione di data, giudicate voi.

from termgraph import Data, VerticalChart, Args, Colors

values = [23, 45, 56, 78, 32, 67, 45]
data_list = [[v] for v in values]

data = Data(
    data=data_list,
    labels=["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
)

args = Args(
    title="Daily Website Visits",
    colors=[Colors.Cyan],
    width=15
)

chart = VerticalChart(data, args)
chart.draw()

Output

Esempio 7 — Histogram

termgraph include anche una istogramma che suddivide i dati in intervalli continui.

from termgraph import Data, HistogramChart, Args, Colors

# Histogram chart
# Note: For histograms, data should be the raw values you want to bin
data = Data(
    data=[[12.5, 15.3, 17.6, 18.7, 22.1, 25.6, 28.9, 32.4, 35.8, 38.2, 39.1, 40.4, 41.7]],
    labels=["Temperature Readings"]
)

args = Args(
    width=40,
    bins=5,  # Number of bins
    title="Temperature Distribution",
    colors=[Colors.Red]
)

chart = HistogramChart(data, args)
chart.draw()

Output

Facciamo spazio... 😊

Nel grafici di termgraph, è possibile aggiungere un distanziamento tra le barre.

Il parametro space_between=True passato a Args permette di inserire uno spazio verticale tra i gruppi di barre associati alle etichette. Questo è particolarmente utile quando si utilizza una sola serie di dati, perché migliora la separazione visiva tra le righe e riduce l’effetto di disallineamento percepito tra barre di diverse etichette.

Se supportato dalla versione della libreria in uso, questo parametro rende il grafico più leggibile senza alterare i valori rappresentati.

from termgraph import Data, Args, BarChart, Colors

data = Data(
    data=[[5, 8], [3, 6], [7, 2]],
    labels=["Task 1", "Task 2", "Task 3"]
)

args = Args(
    title="Durata task",
    width=40,
    colors=[Colors.Cyan, Colors.Blue],
    space_between=True
)

chart = BarChart(data, args)
chart.draw()

Output

Quando usare `termgraph` via Python

L’uso programmatico di termgraph è ideale quando:

stai scrivendo script di monitoraggio
vuoi output visuali nei log
lavori su server senza interfaccia grafica
stai creando tool CLI con feedback immediato

Utilizzo di `termgraph` da linea di comando (CLI)

Oltre all’uso tramite API Python, termgraph può essere utilizzato anche direttamente da linea di comando. Questa modalità è particolarmente utile per analizzare rapidamente file di dati o per integrare visualizzazioni semplici in script shell e pipeline.

L’idea di base è fornire a termgraph un file di testo contenente i dati numerici, uno per riga, e lasciare che lo strumento generi automaticamente il grafico nel terminale.

La versione CLI supporta molte opzioni avanzate, tra cui:

personalizzazione della larghezza del grafico
colori ANSI per le barre
grafici impilati
etichette multiple
calendar heatmap

L’utilizzo da CLI rende termgraph uno strumento molto flessibile per ispezionare dati al volo senza scrivere codice Python, mantenendo comunque una resa visiva chiara e leggibile direttamente nel terminale.

Esempio di utilizzo da linea di comando

Di seguito un esempio semplice di utilizzo di termgraph da CLI. Supponiamo di avere un file di dati data.dat con il seguente contenuto:

Gennaio   120
Febbraio  340
Marzo     290
Aprile    410

È possibile generare un grafico a barre direttamente nel terminale eseguendo il comando:

termgraph data.dat --title "Vendite mensili" --width 50

Output

Questo comando legge i dati dal file, associa automaticamente le etichette ai valori e disegna un grafico a barre orizzontale con titolo personalizzato.

Inoltre, da cli, è possibile utilizzare il calendario con i dati organizzati in questo modo salvati in un file cal_2025.dat:


  2025-10-22      5.05
  2025-10-28     13.10
  2025-11-03      3.60
  2025-12-10      4.70
  2026-01-26      3.77

Nel terminale eseguire il seguente comando:

termgraph --calendar --start-dt 2025-09-30 cal_2025.dat

Output

L’approccio da linea di comando è ideale per analisi rapide, debugging e report testuali senza dover scrivere codice Python.

Conclusione

L’API Python di termgraph consente di creare visualizzazioni leggibili e immediate direttamente nel terminale, mantenendo il codice semplice e senza dipendenze pesanti.
È una soluzione elegante per chi vuole un compromesso tra leggibilità e minimalismo.

Link utili

Follow me #techelopment

Official site: www.techelopment.it
facebook: Techelopment
instagram: @techelopment
X: techelopment
Bluesky: @techelopment
telegram: @techelopment_channel
whatsapp: Techelopment
youtube: @techelopment

Techelopment

Cerca nel blog