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_yfor scatter, line, and area charts. - Error Bars —
error_yfor bar, scatter, and line charts. - Threshold Lines — Horizontal/vertical reference lines on scatter/line charts.
- Custom Ticks & Formatters —
custom_xticks,custom_yticks,tick_formatterfor full axis control. - Theme Presets — 7 built-in themes (default, dark, light, monokai, ocean, forest, sunset).
- Multi-Figure Layout —
Figureclass 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
termtplotlibcommand. - 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:
- Overview
- Installation
- Quick Start
- Chart Types
- API Reference
- Configuration
- Advanced Features
- Output & Formatting
- Examples
- Contributing
- Changelog
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.