Skip to main content

termatplotlib

A lightweight and elegant Python library for rendering stunning ASCII plots directly in your terminal. Zero dependencies.

Features

  • 28 Chart Types — Bar, grouped bar, stacked bar, diverging bar, vertical bar, scatter, line, pie, histogram, area, box plot, violin plot, heatmap, calendar heatmap, candlestick, sparkline, radar, waterfall, gantt, step chart, bubble chart, strip plot, sankey, funnel, bullet, donut, pareto, wordcloud.
  • Logarithmic Axes — log_x / log_y for scatter, line, and area charts.
  • Error Bars — error_y for bar, scatter, and line charts.
  • Threshold Lines — Horizontal/vertical reference lines on scatter/line charts.
  • Custom Ticks & Formatters — custom_xticks, custom_yticks, tick_formatter for full axis control.
  • Theme Presets — 7 built-in themes (default, dark, light, monokai, ocean, forest, sunset).
  • Multi-Figure Layout — Figure class to compose multiple charts together.
  • Configuration System — set_default() / get_default() / reset_defaults() for global styling.
  • CLI Tool — Pipe data from stdin directly into charts via termtplotlib command.
  • Customization — Titles, axis labels, colors, markers, legends, axis limits, grid lines.
  • File Output — Save plots to text files (ANSI codes automatically stripped).
  • Terminal Auto-Detect — Automatically fits to your terminal width.
  • Multi-Series — Plot multiple data series on the same chart.
  • No Dependencies — Pure Python, no external packages required.

Installation

pip install termatplotlib

Or from source:

git clone https://github.com/rkriad585/termatplotlib
cd termatplotlib
pip install .

Quick Start

import termatplotlib as tpl

# Bar chart
tpl.bar(["A", "B", "C", "D"], [10, 20, 15, 5],
        title="My Chart", xlabel="Value", color="red")

Chart Types

Bar Chart

tpl.bar(labels, values, title=None, xlabel=None, ylabel=None,
        color=None, max_width=None, output_file=None, error_y=None)

Grouped Bar Chart

tpl.grouped_bar(labels, values, title=None, xlabel=None, ylabel=None,
                colors=None, max_width=None, output_file=None)

Stacked Bar Chart

tpl.stacked_bar(labels, values, title=None, xlabel=None, ylabel=None,
                colors=None, max_width=None, output_file=None)

Scatter Plot

data = [
    {'x': [1, 2, 3], 'y': [4, 5, 6], 'color': 'red', 'marker': 'o',
     'label': 'Series 1', 'error_y': 0.5},
]
tpl.scatter(data, title="My Plot", xlabel="X", ylabel="Y",
            legend=True, grid=True, log_y=True, output_file="plot.txt")

Line Chart

data = [
    {'x': [0, 1, 2], 'y': [0, 1, 4], 'color': 'green',
     'marker': '*', 'label': 'Quadratic', 'error_y': 0.2},
]
tpl.line(data, title="Line Plot", width=50, height=20, legend=True, grid=True)

Area Chart

tpl.area(data, title="Area Under Curve", stacked=False, legend=True, log_y=True)

Pie Chart

tpl.pie(labels, values, title="My Pie", radius=10, legend=True)

Histogram

tpl.hist(data, bins=10, title="Histogram", xlabel="Value", ylabel="Frequency",
         color="magenta", width=None, height=10)

Box Plot

tpl.boxplot(data, labels=["Group A", "Group B"], title="Comparison",
            color="cyan", width=50, height=20)

Heatmap

data = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
tpl.heatmap(data, row_labels=["A", "B", "C"], col_labels=["X", "Y", "Z"],
            title="Heatmap", color="red")

Vertical Bar Chart

tpl.vertical_bar(["A", "B", "C"], [10, 20, 15], height=15, title="Vertical")

Diverging Bar Chart

tpl.diverging_bar(["Profit", "Loss"], [100, -30], baseline=0, colors=["green", "red"])

Sparkline (inline mini-chart)

tpl.sparkline([1, 5, 22, 13, 5], title="Trend", color="green")

Candlestick Chart (OHLC)

data = [
    {'open': 100, 'high': 110, 'low': 95, 'close': 105},
    {'open': 105, 'high': 115, 'low': 100, 'close': 102},
]
tpl.candlestick(data, width=40, height=15, title="AAPL")

Violin Plot

tpl.violinplot([[1, 2, 3, 4, 5], [2, 3, 4, 5, 6]],
               labels=["A", "B"], title="Distribution")

Calendar Heatmap

tpl.calendar_heatmap({"2026-01-01": 5, "2026-06-15": 10}, title="Activity")

Radar Chart

tpl.radar(["Speed", "Power", "Agility", "Stamina", "Intelligence"],
          [8, 6, 9, 5, 7], width=30, title="Attributes", fill=True, color="red")

Waterfall Chart

tpl.waterfall(["Revenue", "Costs", "Tax", "Net Profit"],
              [1000, -300, -100, 600], width=60, title="P&L Bridge")

Gantt Chart

tasks = [
    {'label': 'Research', 'start': 0, 'end': 5},
    {'label': 'Design',   'start': 3, 'end': 8},
    {'label': 'Dev',      'start': 6, 'end': 12},
    {'label': 'Test',     'start': 10, 'end': 14},
]
tpl.gantt(tasks, width=60, title="Project Timeline")

Step Chart

tpl.step([{'x': [0, 1, 2, 3], 'y': [0, 1, 1, 4]}],
         width=40, height=15, title="Step", grid=True, legend=True)

Bubble Chart

tpl.bubble([{'x': [1, 2, 3, 4], 'y': [10, 20, 15, 30],
             'size': [2, 8, 4, 12], 'label': 'Products'}],
           width=40, height=15, title="Bubble Chart", legend=True)

Strip Plot

tpl.strip([1, 2, 2, 3, 3, 3, 4, 5, 6], width=40, title="Distribution", color="cyan")

Sankey Diagram

nodes = ["Revenue", "Costs", "Tax", "Profit"]
links = [
    {"source": "Revenue", "target": "Costs", "value": 400},
    {"source": "Revenue", "target": "Tax", "value": 200},
    {"source": "Revenue", "target": "Profit", "value": 400},
]
tpl.sankey(nodes, links, width=60, title="Cash Flow")

Funnel Chart

tpl.funnel(["Awareness", "Interest", "Desire", "Action"],
           [1000, 500, 200, 50], width=50, title="Sales Pipeline", color="cyan")

Bullet Chart (KPI Gauge)

tpl.bullet(["Revenue", "Users", "Satisfaction"],
           [85, 70, 90], [100, 80, 95], width=60, title="Dashboard")

Donut Chart

tpl.donut(["Product", "Service", "Subscription", "Other"],
          [40, 30, 20, 10], title="Revenue Mix", legend=True, center_label="Total")

Pareto Chart

tpl.pareto(["Issue A", "Issue B", "Issue C", "Issue D"],
           [50, 30, 15, 5], width=60, title="Bug Priority", show_80_line=True)

Word Cloud

tpl.wordcloud({"python": 10, "data": 8, "chart": 5, "terminal": 4,
               "ascii": 3, "visualization": 3, "library": 2},
              width=50, title="Tag Cloud")

Figure (Multi-Chart Layout)

fig = tpl.Figure(title="Dashboard")
fig.add_chart(tpl.bar, ["A", "B"], [10, 20], max_width=40, color="red")
fig.add_chart(tpl.pie, ["X", "Y"], [30, 70])
fig.render()
fig.savefig("dashboard.txt")

Threshold Lines

tpl.scatter([{'x': [1, 2, 3], 'y': [4, 5, 6]}],
            thresholds=[{'axis': 'y', 'value': 5, 'color': 'red'}])

Custom Ticks & Formatters

tpl.scatter([{'x': [1, 2, 3], 'y': [4, 5, 6]}],
            custom_xticks=[1, 2, 3],
            tick_formatter=lambda v: f"${v:.0f}")

Themes

tpl.apply_theme('monokai')
tpl.bar(["A", "B"], [10, 20])

CLI (stdin pipeline)

echo "1,5,22,13,5" | termatplotlib --type sparkline --color green
echo "10,20,15,30,25" | termatplotlib --type bar --labels "A B C D E" --title "Data"

Parameters

Parameter Used By Description
title All Chart title centered at top
color bar, scatter, line, hist, boxplot, heatmap, sparkline, radar, strip, funnel Chart color (named)
colors grouped_bar, stacked_bar, diverging_bar, sankey, wordcloud List of colors per series
colors_list radar List of axis colors
output_file All Save to file (no ANSI codes)
legend scatter, line, area, pie, step, bubble, donut Show data legend
width scatter, line, area, boxplot, heatmap, vertical_bar, radar, bubble, gantt, sankey, funnel, bullet, pareto, wordcloud Plot width in chars
height scatter, line, area, hist, boxplot, vertical_bar, violin, candlestick, bubble, strip, pareto, wordcloud Plot height in chars
max_width bar, grouped_bar, stacked_bar, diverging_bar, waterfall Max chart width
bins hist Number of histogram bins
marker scatter, line, area, bubble (per series) Point marker character
stacked area Stack series on top of each other
log_x, log_y scatter, line, area Logarithmic axes
error_y bar (function param), scatter, line (per series) Error bar magnitude
grid scatter, line, area, step Show grid lines
xlim, ylim scatter, line, area, step Custom axis limits
thresholds scatter, line, step Reference lines [{axis, value, color, char}]
custom_xticks, custom_yticks scatter, line, area Explicit tick positions
tick_formatter scatter, line, area Custom tick label formatter
palette heatmap, calendar_heatmap List of colors for data range
baseline diverging_bar Center value for divergence
color_up, color_down, color_total candlestick, waterfall Directional colors
fill radar Fill polygon interior
scale_max radar Fixed scale maximum
bar_char gantt Character for bar drawing
jitter strip Stack dots in columns
show_percent funnel Show % of first stage
color_actual, color_target bullet Actual vs target colors
center_label donut Text in center hole
show_80_line pareto Show 80% reference line

Configuration System

tpl.apply_theme('monokai')                # apply built-in theme
tpl.set_default(width=80, height=30, color='blue', legend=True)
tpl.get_default('color')                  # 'blue'
tpl.reset_defaults()                      # clear all defaults

Themes

default, dark, light, monokai, ocean, forest, sunset

Colors

black, red, green, yellow, blue, magenta, cyan, white

Markers

Any single character. Common choices: 'o', 'x', '*', '.', '+', '#'

CLI Examples

# Bar chart from stdin
echo "10,20,15,30" | termatplotlib --type bar --labels "A B C D" --title "Sales" --color blue

# Sparkline from stdin
echo "1,5,22,13,5,8,3,10" | termatplotlib --type sparkline --color green

# Histogram from stdin
echo "1 2 2 3 3 3 4 5 5 6" | termatplotlib --type hist --bins 5 --title "Distribution"

# Step chart from stdin
seq 1 10 | termatplotlib --type step --title "Step" --grid

# Strip plot from stdin
echo "1 1 1 2 2 3 3 3 3 4 5 5 6" | termatplotlib --type strip --color cyan

# Radar chart from stdin
echo "8 6 9 5 7" | termatplotlib --type radar --labels "Speed Power Agility Stamina Intel" --color red

# Funnel chart from stdin
echo "1000 500 200 50" | termatplotlib --type funnel --labels "Aware Interest Desire Action" --color cyan

# Pareto chart from stdin
echo "50 30 15 5" | termatplotlib --type pareto --labels "A B C D" --width 60 --title "Priority"

Docker

# Build the image
docker build -t termatplotlib .

# Run as CLI
docker run --rm termatplotlib -- --type bar --labels "A B C" --data "10 20 15"

# Run with pipe
echo "1,5,22,13,5" | docker run --rm -i termatplotlib --type sparkline --color green

Scripts

Script Platform Usage
run.sh Unix/macOS ./run.sh bar --labels "A B" --data "10 20"
run.cmd Windows CMD run.cmd bar --labels "A B" --data "10 20"
run.ps1 Windows PowerShell .\run.ps1 bar --labels "A B" --data "10 20"

Running Tests

pytest

Documentation

Full documentation is available in the docs/ folder:

License

MIT

Metadata

Release files for termatplotlib 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for termatplotlib 0.6.0
File Size Uploaded Provenance Actions
termatplotlib-0.6.0.tar.gz 37.9 kB Without provenance Details for termatplotlib-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for termatplotlib 0.6.0
File Interpreter ABI Platform Actions
termatplotlib-0.6.0-py3-none-any.whl Python 3 none any Details for termatplotlib-0.6.0-py3-none-any.whl

Total release size: 82.7 kB

Release files / termatplotlib-0.6.0.tar.gz

Download URL termatplotlib-0.6.0.tar.gz
Size 37.9 kB
Tags Source
SHA-256 checksum
How to use checksums
116f72fc35491a4055ce7b461501dc945f8900d2fa8737530be9b9c56393b8ee
BLAKE2b-256 checksum
How to use checksums
d6704cd4387814bf5fe97b7fe91774cf5202662831584aa959687bd15d8a6bbf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.4

Release files / termatplotlib-0.6.0-py3-none-any.whl

Download URL termatplotlib-0.6.0-py3-none-any.whl
Size 44.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
42bfa991323520ee5a56365c8273c3801e359bb2f11ac8e6a7e94edc3e6eeb92
BLAKE2b-256 checksum
How to use checksums
b58802ae593b9e8fc02d70a36ceb74940ad80e6629774db3e4def4bc06b108e1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.4

Security for termatplotlib 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page