Install matra

on this page
grade8.0density0.54compression0.60

Install matra as a Rust library, a command-line binary or a Python package, then check that it works. Each route is one command; take the one for the language you call matra from, or more than one. Platforms and models lists what each route needs and installs, and One core, three install routes explains why the commands look as they do.

grade11.2density0.53compressionnone

To check a release file before you install it, follow Verifying a release in the security policy.


Requirements

grade7.0density0.53compression0.61

For the Rust library and the CLI, and for the Python package on a platform with no wheel, install Rust 1.88 or later (check with rustc --version) and a C++ compiler. A C compiler on its own is not enough: without C++ the build stops with error occurred in cc-rs: failed to find tool "c++".

PlatformPackage
Debian, Ubuntuapt install build-essential
Fedora, RHEL, Rocky, Almadnf install gcc-c++
Alpineapk add g++
Archpacman -S base-devel
macOSxcode-select --install
grade10.0density0.60compression0.57

For the Python package, use Python 3.12 or later (check with python3 --version, or python --version inside an activated virtual environment; stock macOS has only python3). Python wheels lists the platforms with a prebuilt wheel; on any other, and on a free-threaded interpreter, pip builds from source and needs the Rust toolchain and the C++ compiler above.


The Rust library

cargo add matra@0.3
grade12.0density0.55compressionnone

The default features include udpipe, so matra::Engine::new() builds the pinned UDPipe parser without a feature flag. The UDPipe adapter itself is private to the crate: you reach it through Engine, and a parser of your own reaches it through Engine::with_parser.


The CLI binary

cargo install matra --version '^0.3' --features cli
grade9.8density0.52compressionnone

--features cli is required: the binary is gated behind it. This compiles from source and places the binary in your cargo bin directory, which can take a minute or more. Confirm it landed:

matra --version
gradenonedensity1.00compressionnone

Expected output:

matra 0.3.0
features: udpipe cli
grade11.1density0.53compressionnone

The second line names the features this build was compiled with, so the Python package's banner below is longer.


The Python package

pip install 'matra>=0.3'    # or: uv add 'matra>=0.3'
grade7.2density0.51compression0.59

This installs the library and the matra command together; the command is the same program as the CLI binary above, so uvx 'matra>=0.3' analyze essay.md and the installed binary do the same thing. Keep the version floor in the line: why the install lines name a version says what an unpinned one can give you.

grade5.9density0.50compressionnone

On a platform with a wheel this installs in seconds. Its version banner reads:

matra 0.3.0
features: udpipe model2vec python cli
grade9.8density0.53compressionnone

The verify step below doubles as the check: if import matra fails there, the package did not install correctly.


The English model

grade9.0density0.56compressionnone

There is nothing to install. The library, the CLI and the Python package each download the English UDPipe model (about 16 MB) on first use, verify it against a pinned hash, and cache it in the model directory, by default ~/.local/share/matra/models.

grade11.1density0.63compressionnone

To keep it somewhere else, set MATRA_MODEL_DIR, pass --model-dir to the CLI, or pass the directory through Config::with_model_dir in Rust. Python reads MATRA_MODEL_DIR. The model directory gives the full resolution order, and the model download what happens when a download fails its check.


Model licenses

grade8.3density0.55compression0.58

matra's code is MIT, and the two models it downloads are separate works with licenses of their own. The English parsing model comes from LINDAT under CC BY-NC-SA 4.0, which does not permit commercial use; read it before you use matra commercially. The embedding model, potion-base-8M, comes from Hugging Face under MIT per its model card, and is used for semantic clusters only. Model licenses has both in a table, with links to the license texts.

grade6.3density0.65compressionnone

The command line, the config file, Rust and Python always use this model. No surface loads a different UDPipe model file: the model is a pin.


Verify the install

grade15.0density0.50compressionnone

Run this once. No arguments and no environment: it resolves the model directory, downloads and caches the model on this first run, then parses a sentence through it and prints two results:

import matra

engine = matra.Engine()

doc = engine.analyze("The committee approved the proposal without debate.")
print("sections:", len(doc["sections"]))
print("vocabulary_ttr:", doc["metrics"]["vocabulary_ttr"])
grade6.9density0.52compressionnone

To name the directory, set MATRA_MODEL_DIR before the call. Use a real path: the value is used unchanged, so ~ is not expanded.

gradenonedensity1.00compressionnone

Expected output:

sections: 1
vocabulary_ttr: 0.8571428571428571
grade8.6density0.50compression0.54

That first run fetches the model from a university server in Prague, and before it does, matra.Engine() writes two lines to standard error: what is downloading, its size and where to, then the model's licence. They are the lines the command line prints for the same download. Cold starts measured on a fast connection ranged from 3 to 35 seconds; on a slow network it takes longer, and the call is waiting on the network rather than working. Every run after that loads the cached file and touches no network, in about a second.

grade9.4density0.55compression0.53

If matra.Engine() raises OSError (a matra.IoError), either the download never arrived or the model directory could not be written, and the message says which by naming the URL or the path, as details["url"] or details["path"] do. Check your network connection first; then run matra config show to see which directory matra resolved and check the permissions on it. If it raises RuntimeError (a matra.ModelInvalidError), bytes did arrive and then failed the pinned hash check; run the snippet again.


What you have

  • matra installed as a Rust crate, a CLI binary, a Python package, or some combination, all from the same 0.3.x core.
  • The English UDPipe model cached in the resolved model directory, verified against a pinned hash.
  • A confirmed working call from matra.Engine() through analyze() to a result.
grade9.0density0.50compressionnone

Next: Your first analysis walks through what that result holds, or go to Rust, Python or CLI for the surface you are calling from.

This page, measured by matra 0.3.0 with english-ewt-ud-2.5-191206: 21 paragraphs, in the margin. the data