YouPlot: terminal plots from TSV and CSV pipelines

What YouPlot solves for shell users

Most data work starts in a terminal and then leaves it. You run awk, sort, cut and uniq, and at the moment you want to see the shape of the result you either export to a file and open a notebook, or you squint at a column of numbers. YouPlot exists to close that gap. The README describes it as "a command line tool that draws plots on the terminal", and the usage table shows the two input modes: `cat data.tsv | uplot <command> [options]` for stdin, and `uplot <command> [options] data.tsv ...` for files.

The audience is narrow and specific. It is for people who are already comfortable composing pipelines and who treat a plot as a quick sanity check rather than a deliverable. The README's own examples are telling: sorting files in a directory by size and drawing a bar graph, counting processes by user ID with `ps aux | awk '{print $1}' | uplot count`, counting gene annotations per chromosome from a GENCODE GFF3 file. These are inspection tasks, not publication figures. If you need axes you can annotate, a legend you can drag, or an export at 300 dpi, YouPlot is the wrong layer of the stack.

How uplot reads a column and draws it

The mechanism is a Ruby script that consumes delimited text and hands the parsed series to UnicodePlot, the library the README credits with the rendering. There is no server, no daemon and no intermediate file format. Data flows in as text, is split on a delimiter, and is emitted as characters to a terminal stream.

That last point has a consequence people miss. The README states that by default the plot is written to standard error output, not standard output. This is deliberate: it means `uplot` can sit in the middle of a pipeline without contaminating the data stream. The README documents the counterpart, `pipeline1 | uplot <command> -O | pipeline2`, which takes input from stdin and writes data to stdout. So the tool has two distinct roles, a terminal renderer and a pass-through stage, and the flag you choose decides which one you get.

The subcommand list is compact. `bar`, `hist`, `line`, `lines`, `s`, `d`, `box`, `count` and `color` are the documented short forms for barplot, histogram, lineplot, lineplots, scatter, density, boxplot, count and colors. Input shape is inferred from the command rather than declared: a barplot expects labels and values, a histogram expects a single column of numbers, a scatter plot expects columns to pair up, and `-H` tells the parser the first row is a header. The `--fmt yx` option seen in the README's gene example flips the column order so the label column comes second, which matters when `uniq -c` has already put the count first.

Installing youplot and drawing a first plot

The README lists five install routes. On macOS, Homebrew. Everywhere Ruby is available, the gem. There are also Nix, Guix and conda paths, the last of which installs Ruby and a compiler toolchain from conda-forge before the gem. Pick one; do not stack them.

brew install youplot

Or, if you already have a Ruby toolchain:

gem install youplot

After installation the executable is `uplot`, which the README notes is the shortened form of `youplot`; either name works. The quickest real check is the offline example the README gives for the barplot, which sorts files in a directory by size and graphs them. It uses `-d ' '` to set the delimiter to a space, because `ls -l` output is space separated rather than tab or comma separated.

ls -l | awk '{print $9, $5}' | sort -nk 2 | uplot bar -d ' '

You should see a horizontal bar chart painted with block characters, one bar per file, with the largest at the bottom after the sort. If you get an empty chart, the delimiter is the first thing to check, followed by whether the awk fields actually line up with the columns you expect.

The README's other offline examples are worth keeping as templates because they avoid network fetches. A sine wave from Python piped straight into a line plot:

python3 - <<'PY' | uplot line
from math import sin, pi

for i in range(101):
    print(f"{i*pi/50}\t{sin(i*pi/50)}")
PY

The tab between the two printed values is the default delimiter, which is why no `-d` flag appears. The README also ships fixture-based examples that read from the repository's own test data, for instance `cat test/fixtures/iris.csv | cut -f1-4 -d, | uplot scatter -H -d, -t IRIS`, where `-H` marks the header row and `-d,` switches to comma separation.

The count subcommand and its documented speed problem

YouPlot's `count` subcommand is the one place the README volunteers a performance caveat, and it is worth reading literally. The note says count "is not very fast because it runs in a Ruby script" and adds that this is fine as long as the data size is small.

The README then gives the fix, which is to stop using count and let the shell do the counting instead. Its gene-annotation example is rewritten as `cat gencode.v35.annotation.gff3 | grep -v '#' | grep 'gene' | cut -f1 | sort | uniq -c | sort -nrk1 | uplot bar --fmt yx -d ' ' -t "The number of human gene annotations per chromosome" -c blue`. The counting moves to `sort | uniq -c`, which is written in C, and YouPlot only renders the result. The `--fmt yx` flag is the part that makes this work, because `uniq -c` emits count-then-label and the barplot wants label-then-value by default.

This is a good design signal. The author is not claiming Ruby aggregation is competitive with coreutils. The practical rule that falls out of it: use `count` for a few thousand lines from `ps` or a small log, and switch to `sort | uniq -c` the moment the input is a multi-gigabyte annotation file.

Where YouPlot stops being the right tool

The rendering target is the constraint. UnicodePlot draws with characters, so the resolution of a scatter plot is bounded by the width and height of your terminal, which the README exposes as `-w` and `-h` (the AirPassengers example uses `-w 50 -h 15`). Two points that fall inside the same character cell are indistinguishable. For density and scatter plots over thousands of rows, that means the picture shows you where mass is, not what any individual observation did.

There is no interactivity. You cannot pan, zoom, hover, or select a series. There is no documented way to write a PNG or SVG; the output is a terminal stream. If the plot is going into a report, a slide, or a pull request comment, you are going to want a real plotting library, and YouPlot will only ever be the thing you used to check your assumptions before writing that script.

Platform is the second gap. The README documents Homebrew, RubyGems, Nix, Guix and conda. Windows is not among them, and the related searches include people asking about `youplot windows` and `youplot ubuntu` specifically, which suggests the install story is not obvious on those platforms. The README does point at YouPlot2, described as an "Experimental project with pre-built binaries", which is the closest thing to a native-binary answer, but the word experimental is the README's own.

Finally, the dependency on Ruby is real. If your environment has no Ruby and no package manager willing to provide one, the conda route installs Ruby and compilers from conda-forge before the gem, which is a heavier footprint than a single static binary.

YouPlot against gnuplot, plotext and bashplotlib

The alternatives people search for alongside YouPlot split into two camps, and the difference is architectural rather than cosmetic.

Gnuplot is a plotting program with its own command language and a wide range of output terminals, including image formats and interactive windows. It can render to a terminal with the dumb or sixel terminals, but that is one output mode among many. YouPlot has exactly one output mode and no scripting language of its own; the pipeline is the script. If you need the same figure reproduced as a PNG in CI and as a terminal preview locally, gnuplot covers both and YouPlot covers one.

Plotext and bashplotlib are the closer comparisons, because they share the terminal-only premise. Plotext is a Python library, so it fits naturally inside a Python program and can be called as a function on arrays you already hold in memory, whereas YouPlot is a separate process that expects serialized text on a pipe. Bashplotlib is also Python and also terminal-oriented, and its scope is narrower. The trade-off is the usual one: a library gives you programmatic control and keeps you inside one language, a CLI gives you composability with awk, sort, cut and grep without importing anything. YouPlot's README leans hard on that second property, and every example it gives is a pipeline.

Maintenance, licence and what an upgrade costs

The repository is not archived, and the last push was on 2026-06-22. Release v0.5.0 is dated 2026-05-24, following v0.4.6 in July 2024 and v0.4.5 in January 2023. That spacing is worth noting if you are planning around it: the gap between v0.4.5 and v0.4.6 was roughly eighteen months, so a quiet period is not by itself evidence that the project has stopped.

The licence is MIT, per the repository metadata and the LICENSE.txt file at the top level. MIT is permissive: it allows use, modification and redistribution provided the copyright notice and permission notice are retained. That is a statement about the licence text, not legal advice about your situation; if you are vendoring the gem into a distributed product, have your own counsel read LICENSE.txt rather than this paragraph.

Upgrade cost is low in the ordinary case, because the tool is a single executable with a small flag surface and no configuration file. There is no schema to migrate and no state on disk. The realistic breakage risk sits in two places: the Ruby version your runtime provides, which youplot.gemspec constrains, and the subcommand flag surface, which changed between the 0.4.x and 0.5.x lines. Pinning the gem version in your Gemfile and reading the release notes before bumping is cheaper than discovering a changed default in a pipeline that runs unattended.

Editorial conclusion

Adopt YouPlot if your data already flows through a shell pipeline and you want a visual check without leaving the terminal or writing a plotting script. Skip it if you need interactive charts, huge datasets, or a Windows-native install path, since the README documents brew, gem, nix, guix and conda routes and the related searches show people asking about Windows and Ubuntu separately. Before relying on it, verify two things: that your Ruby version satisfies youplot.gemspec, and whether you need -o to send the plot to standard output instead of the default standard error, because that choice decides whether the plot survives the next pipe stage.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. red-data-tools/YouPlot on GitHub
5. Releases