udpipe-rs

With the download feature

Use this if you want to fetch pre-trained models by language tag (e.g. download_model("english-ewt", ".")) or from a custom URL. This enables the download feature and adds the ureq dependency.

Add to your Cargo.toml:

[dependencies]
udpipe-rs = { version = "0.1", features = ["download"] }

Or via command line:

cargo add udpipe-rs --features download

Usage

Load a model and parse text

Create a parser with [Model::parser] for a given text; it returns an iterator over sentences. Each sentence contains words and optional multiword tokens and comments. Use any .udpipe model file at any path.

use udpipe_rs::Model;

fn main() -> Result<(), udpipe_rs::UdpipeError> {
    // Load a model from a path (any language, any location)
    let model = Model::load("path/to/model.udpipe")?;

    // Create a parser for the text
    let parser = model.parser("The quick brown fox jumps over the lazy dog.")?;

    // Iterate over sentences (each item is Result<Sentence, UdpipeError>)
    for sentence in parser {
        let sentence = sentence?;
        for word in &sentence.words {
            println!("{:<4} {:<10} {:<6} {:<10} {:>2} <- {}",
                word.id,
                word.form,
                word.upostag,
                word.lemma,
                word.head,
                word.deprel
            );
        }
    }
    Ok(())
}

Output:

1    The        DET    the         2 <- det
2    quick      ADJ    quick       5 <- amod
3    brown      ADJ    brown       5 <- amod
4    fox        NOUN   fox         5 <- nsubj
5    jumps      VERB   jump        0 <- root
6    over       ADP    over        9 <- case
7    the        DET    the         9 <- det
8    lazy       ADJ    lazy        9 <- amod
9    dog        NOUN   dog         5 <- obl
10   .          PUNCT  .           5 <- punct

To fetch a model by language tag instead of using a local file, enable the download feature and use [download_model]:

use udpipe_rs::{download_model, Model};

// Requires: udpipe-rs with feature "download"
let model_path = download_model("english-ewt", ".")?;
let model = Model::load(&model_path)?;

Available languages

Pre-trained models are available for 65+ languages. Use [udpipe_rs::AVAILABLE_MODELS] to see the full list:

// Some examples:
// "english-ewt", "english-gum", "english-lines", "english-partut"
// "german-gsd", "german-hdt"
// "french-gsd", "french-sequoia", "french-spoken"
// "spanish-ancora", "spanish-gsd"
// "dutch-alpino", "dutch-lassysmall"
// "chinese-gsd", "japanese-gsd", "korean-gsd"
// ... and many more

for lang in udpipe_rs::AVAILABLE_MODELS {
    println!("{}", lang);
}

Working with morphological features

[Word::feats] is a string of pipe-separated key-value pairs (e.g. "VerbForm=Fin|Mood=Ind|Tense=Pres"). Parse it as needed:

use udpipe_rs::Model;

fn main() -> Result<(), udpipe_rs::UdpipeError> {
    let model = Model::load("path/to/your-model.udpipe")?;
    let parser = model.parser("Run quickly!")?;

    for sentence in parser {
        let sentence = sentence?;
        for word in &sentence.words {
            // Check for imperative: look for Mood=Imp in feats
            if word.upostag == "VERB" || word.upostag == "AUX" {
                if word.feats.contains("Mood=Imp") {
                    println!("Found imperative: {}", word.form);
                }
            }
            // Parse feats for specific keys (e.g. Tense=Pres)
            for pair in word.feats.split('|') {
                if let Some((k, v)) = pair.split_once('=') {
                    if k.trim() == "Tense" {
                        println!("{} has tense: {}", word.form, v.trim());
                    }
                }
            }
        }
    }
    Ok(())
}

Working with sentence structure

The parser yields one [Sentence] per call to [Iterator::next]. Each sentence has words, multiword_tokens, and comments:

use udpipe_rs::Model;

fn main() -> Result<(), udpipe_rs::UdpipeError> {
    let model = Model::load("english-ewt-ud-2.5-191206.udpipe")?;
    let parser = model.parser("Hello world. Goodbye world.")?;

    for (idx, sentence) in parser.enumerate() {
        let sentence = sentence?;
        println!("--- Sentence {} ---", idx + 1);
        for word in &sentence.words {
            println!("  {}: {} ({})", word.id, word.form, word.upostag);
        }
    }
    Ok(())
}

Download from custom URL

With the download feature, [download_model_from_url] writes the model to a file at the given path:

use udpipe_rs::download_model_from_url;

download_model_from_url(
    "https://example.com/custom-model.udpipe",
    "custom-model.udpipe",
)?;

Thread Safety

Model is [Send] but not [Sync]. This means:

• You can move a model to another thread (ownership transfer)
• You cannot share &Model across threads simultaneously

For concurrent access, either:

Option 1: Wrap in Mutex (shared model, serialized access)

use std::sync::{Arc, Mutex};
use udpipe_rs::Model;

let model = Arc::new(Mutex::new(Model::load("model.udpipe")?));

let model_clone = Arc::clone(&model);
std::thread::spawn(move || {
    let guard = model_clone.lock().unwrap();
    let parser = guard.parser("Hello world").unwrap();
    for sentence in parser {
        let _ = sentence.unwrap();
    }
});

Option 2: Separate models per thread (parallel access, higher memory)

use udpipe_rs::Model;

std::thread::spawn(|| {
    let model = Model::load("model.udpipe").unwrap();
    let parser = model.parser("Hello world").unwrap();
    for sentence in parser {
        let _ = sentence.unwrap();
    }
});

API Reference

[Sentence]

A parsed sentence from the pipeline.

[Word]

Each parsed word contains:

Features in feats are pipe-separated Key=Value pairs; parse them as needed (e.g. check upostag for VERB/AUX, or search feats for "Mood=Imp").

Examples

Both examples work with any language model at any path.

# Download the English model to a models directory (requires the 'download' feature)
cargo run --example download_model -- english-ewt ./models

# Parse text with that model
cargo run --example parse_text -- ./models/english-ewt-ud-2.5-191206.udpipe "The quick brown fox jumps over the lazy dog."

Models

Pre-trained models for 100+ treebanks are available from the LINDAT/CLARIAH-CZ repository. With the download feature, the [download_model] function fetches from this repository by language tag. Without it, use any .udpipe file at any path with [Model::load].

Requirements

For users: A C++ compiler with C++11 support. The build script compiles UDPipe as a static library automatically.

For contributors: Just Docker. See CONTRIBUTING.md for details.

License

This crate is dual-licensed under MIT OR Apache-2.0.

UDPipe itself is licensed under the Mozilla Public License 2.0.