Platforms and models
on this page
What each of matra's install routes needs and installs, and the models matra downloads. Install matra has the steps; One core, three install routes explains the choices behind them.
Install routes
| Route | Command | Builds from source | Features in the build |
|---|---|---|---|
| Rust library | cargo add matra@0.3 | yes | udpipe (the default) |
| CLI binary | cargo install matra --version '^0.3' --features cli | yes | udpipe cli |
| Python package | pip install 'matra>=0.3' | only where no wheel fits | udpipe model2vec python cli |
The Python package installs the library and the matra command, which is the Rust CLI reached through the extension module, and has no runtime dependencies of its own.
Toolchains
| Needed for | Requirement |
|---|---|
| Every route that builds from source | Rust 1.88 or later, the minimum supported Rust version |
| Every route that builds from source | A C++ compiler: UDPipe is a C++ library, which udpipe-rs builds during the cargo build. A C compiler alone is not enough. |
| The Python package | CPython 3.12 or later |
Python wheels
| Platform | Wheel |
|---|---|
| Linux x86_64, Linux aarch64 | manylinux2014: glibc 2.17 or newer, which covers Debian 11, Ubuntu 20.04, RHEL 8 and Amazon Linux 2 |
| macOS x86_64, macOS arm64 | yes |
| Windows | none; the UDPipe build under MSVC is unverified, so the sdist route there is untested |
The wheels are built against the CPython stable ABI and tagged abi3, so one wheel per platform serves 3.12 and every later 3.x on GIL-enabled CPython. A free-threaded interpreter (python3.14t, for one) accepts a different tag, abi3t, so it gets no wheel on any platform and builds the sdist; pyo3 gains the free-threaded stable ABI at 3.15. Wherever no wheel fits, pip builds the sdist, which needs the toolchains above.
Every release file from 0.2.1 on carries a build provenance attestation; Verifying a release has the commands.
Version requirements
| Requirement | Used by | Accepts |
|---|---|---|
matra@0.3, --version '^0.3' | cargo | 0.3.0 or a later release semver-compatible with it, so not 0.4.0 |
'matra>=0.3' | pip, uv, uvx | 0.3.0 and every later release |
An install line with no version takes the newest release on the registry. 0.1.0 is still published, and its matra command is a separate Python implementation with its own --json shape and a model directory fixed at ~/.matra/models. 0.2 is published too, with the surface Migrate from 0.2 to 0.3 moves you off.
Build features
matra --version prints the version, then the features the build was compiled with:
matra 0.3.0
features: udpipe cli
That is the CLI binary from cargo install. The Python package prints features: udpipe model2vec python cli. Every analysis command behaves the same in both builds except matra clusters, which needs model2vec and refuses, naming it, in a build without; cargo install matra --features cli,model2vec builds one with it.
The model directory
The library, the CLI and the Python package resolve the model directory the same way, first match wins:
- A directory passed explicitly:
--model-diron the command line,Config::with_model_dirin Rust, or the directory argument of the constructors that take one, such asModel2Vec::potion_base_8m. MATRA_MODEL_DIR.- The
modelsdirectory of the data root, which isMATRA_DATA_DIR, else$XDG_DATA_HOME/matra, else~/.local/share/matra. - A pre-existing, non-empty
~/.matra/modelsfrom an older install, when the location in 3 does not exist yet. matra never creates~/.matra; a selected legacy cache is used as the model directory, downloads included.
Where matra keeps things has the config file and data root beside it, and matra config show prints which rung each value came from.
The model download
| Parsing model | Embedding model | |
|---|---|---|
| Fetched by | Engine::new and Engine::from_config, in Rust and in Python, and the command line, on first use | Model2Vec::potion_base_8m, Model2Vec::from_config, their Python forms and matra clusters, on first use |
| Size | 16.3 MB | 30.9 MB, three files |
| Verified against | a SHA-256 pinned in the source | a SHA-256 over the three files, pinned in the source |
| Download cap | 64 MiB | 64 MiB per file |
The download is held in memory, checked against the pinned hash, and written only if it matches, so nothing unverified reaches the model directory and an interrupted transfer leaves nothing behind. A mismatch downloads once more; a second mismatch is an error, and nothing is loaded. A cached parsing model that fails the check is replaced only when new bytes verify, so a re-download that cannot reach the network leaves the file that was there. The embedding model is never written over files already in its directory; Provisioning has what it does instead.
The library prints nothing while it downloads. The command line prints two lines on stderr before either model's download, naming the model, its size, where it is going and its license; --quiet silences them. Errors has what each failure returns.
Model licenses
matra's code is MIT. The models it downloads are separate files, published by other people under licenses of their own.
| Model | Used for | Source | License |
|---|---|---|---|
english-ewt-ud-2.5-191206.udpipe | every parse | LINDAT record 11234/1-3131, published by ÚFAL, Charles University | CC BY-NC-SA 4.0 (Attribution-NonCommercial-ShareAlike 4.0 International) |
| potion-base-8M | semantic clusters only | minishlab/potion-base-8M on Hugging Face | MIT, per its model card |
The parsing model's license does not permit commercial use. The UDPipe models page states that the UDPipe 1 models it publishes for Universal Dependencies are distributed under CC BY-NC-SA. This page reports what the licenses say and does not interpret them; read the license text for the terms.
The command line and the config file always use this parsing model: --model-dir, MATRA_MODEL_DIR and the other settings change where it is stored, not which model it is. models.udpipe, which earlier releases wrote into the config file, is gone, and a file that still sets it fails to load, saying so. No surface loads a different UDPipe model file: the model is a pin.
This page, measured by matra 0.3.0 with english-ewt-ud-2.5-191206: 14 paragraphs, in the margin. the data