# vpype treats a plotter file as a pipeline of commands

> vpype is a Python command line tool for pen plotter vector graphics, and its organising idea is that a drawing is a pipeline: one command loads geometries, the next ones modify them, the last one writes the file. That model is why it can crop, merge and reorder paths for a plotter, export HPGL for vintage hardware, and still serve as a library and a viewer.

**abey79/vpype** — The Swiss-Army-knife command-line tool for plotter vector graphics.

- Repository: https://github.com/abey79/vpype
- Website: https://vpype.readthedocs.io/
- Stars: 978 · Forks: 81
- Language: Python
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/abey79-vpype

## Pipelines of commands, not a single filter

The way vpype works is stated plainly in the README. It works by building so-called pipelines of commands, where each command's output is fed to the next command's input. The commands fall into three kinds, and recognising them makes the rest of the tool obvious. Some commands load geometries into the pipeline, such as the read command, which loads geometries from an SVG file. Other commands modify those geometries, for example by cropping them with crop, or by reordering them to minimise pen-up travels with linesort. Finally, other commands read the geometries in the pipeline for display purposes, such as show, or output to file with write. A pipeline is defined on the command line by typing vpype followed by the list of commands, each with their optional parameters and their arguments. That is a Unix philosophy applied to a domain most people meet through a graphical editor, and it is the reason the tool composes well with shell scripting and with the plug-in system.

## Arguments are required, options are optional

The distinction between an argument and an option in vpype is worth being precise about, because it is where most of the friction with a command line tool comes from. Some commands have arguments, which are always required. A file path must be provided to the read command, and dimensions must be provided to the crop command. A command may also have options, which are optional. The README walks through what that means in practice with a write command, where the option --page-size a4 means that the write command will generate an A4-sized SVG, otherwise it would have the same size as the input file, and where the option --center means that write will center geometries on the page before saving the SVG, otherwise the geometries would have been left at their original location. So the mental model is that arguments are the work the command cannot do without, and options select a variant of that work.

## Fitting artwork to a page

The layout side of the tool is what turns an arbitrary drawing into something a plotter can execute. The README describes layout as laying out existing vector files with precise control on position, scale and page format, and the simplest useful pipeline is three commands long. You read the file, fit it to the margins of a page format, and write the result:

```bash
$ vpype \
  read input.svg \
  layout --fit-to-margins 2cm a4 \
  write output.svg
```

The A4 in that command is the page format and the two centimetres is the margin, and the output is an A4-sized, ready-to-plot SVG. The layout command is also how the tool handles the other end of the problem, since a plotter artwork file that has been drawn in a coordinate system of its own has to be mapped onto the physical page, and controlling position, scale and format together is the difference between a drawing that fits and a drawing that runs off the edge. The same command family also covers creating HPGL output for vintage plotters, which is the export path for hardware that predates SVG entirely.

## Merging and sorting paths to cut plotting time

Optimising an existing SVG file for a faster and cleaner plot is the feature the tool is named for, and the pipeline for it is the one to look at. The README describes it as merging connected lines, sorting them to minimise pen-up distance, randomizing closed paths' seam, and reducing the number of nodes:

```bash
$ vpype \
  read input.svg \
  linemerge --tolerance 0.1mm \
  linesort \
  reloop \
  linesimplify \
  write output.svg
```

Each of those four commands attacks a different cost. linemerge joins paths whose extremities are close to each other, within the provided tolerance, which removes the pen-up travel that would otherwise happen between two nearly touching segments. linesort reorders paths so the pen moves as little as possible between them, which is the classic travelling salesman problem in a plotter context. reloop randomizes the seam of closed paths, which spreads the starting point of a closed contour so the artefact does not always land in the same place. linesimplify reduces the number of nodes. The tolerance argument on linemerge is the one knob worth tuning, since a value that is too large merges shapes that should stay separate.

## Several files into one multi-layer drawing

Multi-colour plotting needs each layer to survive as a separate entity, and the tool has a command form for reading many files at once. The README shows a pipeline that loads several SVG files and saves them as a single multi-layer SVG file, for example for multicoloured drawings:

```bash
$ vpype \
  forfile "*.svg" \
    read --layer %_i% %_path% \
  end \
  write output.svg
```

The forfile and end pair is a loop, and the read command inside it is given two substitutions. The layer is set from the loop index and the file path comes from the matched file, so each iteration contributes a named layer rather than a flattened set of paths. That is the mechanism behind the create, modify and process of multi-layer vector files claim, and it is what makes a drawing with separate colours, separate pens or separate plot passes possible. The viewer is the other half of that workflow, since inspecting the layer and path structure of a result is what the show command is for, and the README gives a pipeline that reads a file and displays it.

## A library and a hardware accelerated viewer

vpype is not only a command line tool. It is also described as a well documented Python library useful to create generative art and tools for plotters, and it includes data structures, utility and I/O functions, as well as a hardware-accelerated flexible viewer for vector graphics. The library layer is what lets the tool be used from a script rather than a shell, and the plotter generative art environment vsketch is built upon vpype, which is the clearest evidence that the library API is stable enough to base another project on. The viewer part explains the optional dependencies in the project file, since a hardware accelerated viewer needs a graphics stack: moderngl, glcontext, PySide6 for the toolkit, matplotlib and Pillow for images. The package data confirms it, with GLSL shader files for the viewer, PNG resources and bundled fonts, including a font pickle for the text rendering that plotter artwork needs.

## Plug-ins, packaging and the version gap

Extensibility is the reason to pick this tool over writing your own script, and the README names the plug-ins that already exist, including vpype-pixelart for plotting pixel art and hatched for half-toning with hatches. The dependency list shows the geometry stack underneath, with Shapely, svgelements, svgwrite, numpy, scipy and pnoise, plus pyphen for hyphenation and asteval for expression evaluation inside the tool, which is how a command can accept a computed value rather than a literal. The command line entry point is declared as a single script, vpype, mapped to the cli module. On packaging, the project file requires Python 3.11 up to but not including 3.14 and classifies the project as Production/Stable, with a poetry.lock for reproducible installs and a justfile whose install target pulls the complete development environment including the docs and dev groups. The tests are pytest based, with pytest-benchmark, pytest-mpl and syrupy for snapshot testing, and mypy and ruff for typing and linting. The version situation is the one loose end, since the published releases include 1.15.0 from 2025-08-04 while the project file already reads 1.16.0a0, and the last push was on 2026-10-07.

## Conclusion

vpype fits a plotter artist who already has SVG artwork and wants it prepared for the machine, since the optimisation commands address the two costs that dominate plotting time, the number of pen-up travels and the number of nodes, and it fits a generative artist who wants the layout and export step to be a script rather than a manual step. It does not fit someone who wants a graphical editor, since the tool is a terminal pipeline with a viewer attached rather than a drawing application, and it does not fit a project stuck on an older Python, since the package requires Python 3.11 up to but not including 3.14. Before you install it, note that the published versions are 1.15.0 from 2025-08-04 while the project file already reads 1.16.0a0, so the release and the development version differ, and check the command reference in the documentation for the options each stage accepts.

## FAQ

### What is vpype?

It is a Swiss Army knife command line tool for plotter vector graphics, and it works by building pipelines of commands where each command's output feeds the next, so a read command loads geometries, transform commands modify them and a write command saves the result.

### How do I optimise an SVG for a pen plotter?

Run the optimisation pipeline with linemerge, linesort, reloop and linesimplify, which merge nearly touching paths, reorder them to cut pen-up travel, randomize the seam of closed paths and reduce the number of nodes.

### Can vpype write multi-layer SVG files?

Yes. The forfile and end commands loop over a set of files, and read with the --layer option and the loop index substitution puts each file into its own layer, which is what multi-colour plotting needs.

### Is vpype only a command line tool?

No. It is also a documented Python library with data structures, utility and I/O functions, plus a hardware accelerated viewer for vector graphics, and the vsketch generative art environment is built on top of it.

### How do I install vpype and what Python does it need?

The project requires Python 3.11 up to but not including 3.14, and the development environment is installed with poetry install -E all --with docs,dev from the justfile. The published releases include 1.15.0 from 2025-08-04 while the project file reads 1.16.0a0.

## Sources

- [abey79/vpype on GitHub](https://github.com/abey79/vpype)
- [License: MIT](https://github.com/abey79/vpype/blob/master/LICENSE)
- [Project website](https://vpype.readthedocs.io/)
- [README](https://github.com/abey79/vpype/blob/master/README.md)
- [Releases](https://github.com/abey79/vpype/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/abey79-vpype