{"id":7506,"library":"plotille","title":"Plotille","description":"Plotille is a Python library that allows users to create plots, scatter plots, histograms, and heatmaps directly in the terminal using Unicode braille dots. It currently stands at version 6.0.5 and is actively maintained with frequent minor and major releases, focusing on terminal-based data visualization without external dependencies.","status":"active","version":"6.0.5","language":"en","source_language":"en","source_url":"https://github.com/tammoippen/plotille","tags":["terminal","plotting","braille","data visualization","charts","CLI","ASCII art","histogram","scatter","heatmap"],"install":[{"cmd":"pip install plotille","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"While `from plotille import plot` works, the official documentation and examples generally prefer `import plotille` and accessing functions/classes as attributes (e.g., `plotille.plot`, `plotille.Figure`).","wrong":"from plotille import plot\nplot(X, Y)","symbol":"plot","correct":"import plotille\nplotille.plot(X, Y)"},{"note":"The `Figure` class is exposed directly under the top-level `plotille` module.","wrong":"from plotille.figure import Figure\nfig = Figure()","symbol":"Figure","correct":"import plotille\nfig = plotille.Figure()"}],"quickstart":{"code":"import plotille\nimport numpy as np\n\nX = np.linspace(0, 2*np.pi, 100)\nY = np.sin(X)\n\nprint(plotille.plot(X, Y, width=70, height=20,\n                     X_label='Angle', Y_label='Sine Value',\n                     linesep='\\n'))\n\n# Example with Figure class\nfig = plotille.Figure()\nfig.width = 70\nfig.height = 20\nfig.x_label = 'Angle'\nfig.y_label = 'Cosine Value'\nfig.plot(X, np.cos(X), label='cos(x)', lc='blue')\nprint(fig.show())\n","lang":"python","description":"This quickstart demonstrates how to create a simple line plot using `plotille.plot` and a more customizable plot using the `plotille.Figure` class. It plots sine and cosine functions in the terminal."},"warnings":[{"fix":"Upgrade to Python 3.10+ or downgrade plotille to a version <= 4.x.","message":"Python 2.7 support was dropped in Plotille v5.0.0. Projects still using Python 2.7 must use Plotille v4.x or earlier.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Review your color-related code for `Dots`, `Canvas`, and `Figure`. Adapt to using `mode` instead of `color_mode` and pass keyword arguments for color functions via `color_kwargs`.","message":"The API for handling colors in `Dots`, `Canvas`, and `Figure` changed significantly in v4.0.0. The `color_mode` argument was renamed to `mode` in many cases, and a `color_kwargs` argument was introduced for finer control over color functions.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Run your applications in a true terminal emulator (e.g., Alacritty, iTerm2, Kitty, Windows Terminal, gnome-terminal) with a font that has good support for Unicode braille characters (e.g., Cascadia Code, Unscii). Avoid running directly in IDE output consoles if alignment issues occur.","message":"Plotille's rendering relies on specific terminal properties (monospaced braille characters, ANSI escape codes for colors). Plots may appear misaligned, garbled, or without colors in non-compliant terminal emulators or IDE output panes that don't correctly interpret these features.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For fine-grained control over datetime axes, explore `x_ticks_fkt` and `register_label_formatter` as described in the documentation or GitHub issues (e.g., issue #57) to provide custom formatting functions for axis labels.","message":"Customizing time-based X-axis labels for real-time or complex time series plots can be challenging. The library's internal tick calculation might not always align perfectly with desired datetime formats or intervals.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"The `color_mode` argument was renamed to `mode` in v4.0.0. Change `color_mode='rgb'` to `mode='rgb'` or similar, depending on your intended color handling.","cause":"Attempting to use the `color_mode` argument with `plotille.plot` or `plotille.Figure` functions/methods in versions 4.0.0 or later.","error":"TypeError: plot() got an unexpected keyword argument 'color_mode'"},{"fix":"Ensure that your `X` and `Y` data sequences have the exact same number of elements before passing them to a `plotille` function.","cause":"The input arrays (or lists) for X and Y coordinates have different lengths, which is not allowed for plotting functions like `plotille.plot` or `plotille.scatter`.","error":"ValueError: X and Y must have the same number of entries."},{"fix":"Ensure your terminal emulator supports UTF-8 encoding and is configured to use it. In Python, you can often mitigate this by setting `PYTHONIOENCODING=utf-8` in your environment or explicitly encoding output (though terminal configuration is preferred). Using `linesep='\\n'` can sometimes help, but the core issue is terminal encoding.","cause":"Your terminal or environment is not configured to correctly display Unicode braille characters (U+2800 onwards) or the output stream's encoding is not UTF-8.","error":"UnicodeEncodeError: 'charmap' codec can't encode character '\\u2800' in position X: character maps to <undefined>"}]}