Asciichartpy

1.5.25 · active · verified Fri Apr 17

Asciichartpy is a lightweight Python library for drawing nice-looking console ASCII line charts directly in your terminal. It offers simple, dependency-free charting for command-line applications and scripts. The current version is 1.5.25, with releases occurring periodically to address minor issues and improvements.

Common errors

```
TypeError: unsupported operand type(s) for +: 'int' and 'str'
```
cause Attempting to plot a series containing non-numeric data (e.g., strings mixed with numbers). `asciichartpy` expects all series values to be integers or floats.

fix Cleanse your data to ensure all values in the series are convertible to numbers. Example: `data = [float(x) for x in raw_data if x.isdigit()]`.
```
AttributeError: module 'asciichartpy' has no attribute 'chart'
```
cause Incorrect function name. The primary plotting function in `asciichartpy` is named `plot`, not `chart`.

fix Call the correct function: `asciichartpy.plot(...)` or `from asciichartpy import plot; plot(...)`.
```
Chart output appears garbled or lines are broken/misaligned.
```
cause This often occurs when the terminal's character encoding is not correctly interpreted, or due to a font issue, especially on Windows or older terminals.

fix Ensure your terminal is using a UTF-8 encoding (e.g., `chcp 65001` on Windows CMD/PowerShell, or check locale settings on Linux/macOS). Using a modern terminal emulator (like Windows Terminal, Alacritty, iTerm2) and a suitable monospaced font (e.g., Fira Code, Source Code Pro) can resolve most rendering issues.

Warnings

gotcha Input data for plotting must be numeric (list of floats or integers). Passing non-numeric types will result in runtime errors.
Fix: Ensure all elements in your input series are integers or floats before passing them to `plot()`.
gotcha For plotting multiple series, the input must be a list of lists. A single list is interpreted as a single series.
Fix: If you have `series1` and `series2`, pass them as `asciichartpy.plot([series1, series2], ...)` not `asciichartpy.plot(series1, series2, ...)`. Each inner list represents one series.
gotcha The visual quality of ASCII charts can vary depending on your terminal emulator, font, and window width. Charts might appear truncated or misaligned in narrow terminals or with non-monospaced fonts.
Fix: Use a monospaced font, ensure your terminal window is sufficiently wide, and experiment with the `height` and `offset` options to optimize rendering for your environment.

Install

pip install asciichartpy Install stable version

Imports

plot
```
from asciichartpy import plot
```

Quickstart

This quickstart demonstrates how to plot a single numeric series and multiple series using `asciichartpy.plot`. It generates a sine wave as sample data and prints the ASCII chart directly to the console. The `height` option is used to control the chart's vertical size.

import asciichartpy
import math

# Generate some sample data (a sine wave)
series_data = [2 * math.sin(i / 10.0) + 5 for i in range(120)]

# Plot the series with a specified height
chart_output = asciichartpy.plot(series_data, {'height': 10})
print(chart_output)

# Plot multiple series
series_data_2 = [1 * math.cos(i / 15.0) + 5 for i in range(120)]
multi_series_output = asciichartpy.plot([series_data, series_data_2], {'height': 12})
print("\n--- Multiple Series ---\n")
print(multi_series_output)

view raw JSON →