📊 View charts in the terminal with termgraph using Python

Posted by

 

termgraph is a Python library designed to represent numerical data directly in the terminal, without external graphics dependencies. Unlike libraries like matplotlib, termgraph produces structured text output, ideal for scripts, CLI tools, and headless environments.

In this article, we'll primarily focus on programmatic use of the library, leveraging the classes exposed by the Python API. Finally, we'll touch on using the library from the command line (cli).

🔗 Do you like Techelopment? Check out the site for all the details!

Installation

pip install termgraph

Python API Basics

The termgraph Python API revolves around three main components:

  • Data → contains values ​​and labels
  • Args → graph configuration (width, title, format, colors, etc.)
  • BarChart / StackedBarChart / CalendarHeatmap → objects that draw the chart

Example 1 — Simple Bar Chart

The bar chart is the most common use case.

from termgraph import Data, Args, BarChart

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

data = Data(values, labels)

args = Args(
   title="Bar Chart Example",
   width=40, 
   format="{:.0f}"
)

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

Output



Example 2 — Bar Chart with Multiple Series

termgraph supports multiple data series for each label.

from termgraph import Data, Args, BarChart

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

labels = ["January", "February", "March"]

data = Data(values, labels)

args = Args(
   title="Product A and B Sales",
   width=50,
   format="{:.0f}"
)

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

Output


Example 3 — Formatting Values ​​and Suffix

You can customize the number format and add a suffix (for example, "K", "MB", "%").

from termgraph import Data, Args, BarChart

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

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

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

Output


Example 4 — Colored bars

termgraph supports ANSI colors to distinguish series.

from termgraph import Data, Args, BarChart, Colors

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

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

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

Output


Example 5 — Stacked Bar Chart

When values ​​represent parts of a total, the stacked chart is very useful.

from termgraph import Data, Args, StackedBarChart

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

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

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

Output


Example 6 — Vertical Bar Chart

Unfortunately, termgraph declares support for vertical bar charts, but the code provided on the official GitHub project website doesn't work very well...
This is the result after fixing the data declaration; judge for yourself.
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


Example 7 — Histogram

termgraph also includes a histogram that divides the data into continuous intervals.

from termgraph import Data, HistogramChart, Args, Colors

# Histogram chart
# Note: For histograms, data should be the raw values ​​you want to bin
date = Date( 
   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

Let's make some space... 😊

In termgraph graphs, you can add spacing between bars.

The parameter space_between=True passed to Args allows you to insert a vertical space between the groups of bars associated with labels. This is especially useful when using a single data series, as it improves the visual separation between rows and reduces the perceived skew between bars of different labels.

If supported by your library version, this parameter makes the chart more readable without altering the displayed values.

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="Task Duration",
   width=40,
   colors=[Colors.Cyan, Colors.Blue],
   space_between=True
)

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

Output


When to use termgraph via Python

Using termgraph programmatically is ideal when:

  • you're writing monitoring scripts
  • you want visual output in logs
  • you're working on servers without a graphical interface
  • you're creating CLI tools with immediate feedback

Using termgraph from the command line (CLI)

In addition to using it via the Python API, termgraph can also be used directly from the command line. This is particularly useful for quickly analyzing data files or integrating simple visualizations into shell scripts and pipelines.

The basic idea is to provide termgraph with a Text file containing the numeric data, one per line, and let the tool automatically generate the graph in the terminal.

The CLI version supports many advanced options, including:

  • Customizable chart width
  • ANSI bar colors
  • Stacked charts
  • Multiple labels
  • Calendar heatmap

Using the CLI makes termgraph a very flexible tool for inspecting data on the fly without writing Python code, while still maintaining a clear and readable visual display directly in the terminal.

Command line example

Below is a simple example of using termgraph from the CLI. Suppose we have a data file data.dat with the following Contents:

January 120
February 340
March 290
April 410

You can generate a bar chart directly in the terminal by running the command:

termgraph data.dat --title "Monthly Sales" --width 50

Output

This command reads data from the file, automatically associates labels with values, and draws a horizontal bar chart with a custom title.

Additionally, from the CLI, you can use the calendar with the data organized in this way saved in a cal_2025.dat file:


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

In the terminal, run the following command:

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

Output

The command-line approach is ideal for quick analysis, debugging, and repText-based visualizations without having to write Python code.


Conclusion

The termgraph Python API allows you to create readable and immediate visualizations directly in the terminal, keeping the code simple and without heavy dependencies.
It's an elegant solution for those who want a compromise between readability and minimalism.


Useful links



Follow me #techelopment

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