Install & Compatibility
Where this runs
tested against v0.5.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.103s · 21.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.9s · import 0.110s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Document
✓ from udapi.core.document import Document
Block
✓ from udapi.core.block import Block
Conllu
✓ from udapi.block.read.conllu import Conllu
✗ import Conllu
Blocks are typically imported from `udapi.block.<category>.<BlockName>`.
Text
✓ from udapi.block.read.text import Text
This quickstart demonstrates how to initialize a `Document`, read a plain text sentence using `read.Text`, tokenize it with `tokenize.Simple`, and then write the resulting (unparsed) document into CoNLL-U format using `write.Conllu`. The output is captured and printed.
import io
from contextlib import redirect_stdout
from udapi.core.document import Document
from udapi.block.read.text import Text
from udapi.block.tokenize.simple import Simple
from udapi.block.write.conllu import Conllu
# Create a new document
doc = Document()
# Read raw text into the document
read_text_block = Text(string="This is a test sentence.")
read_text_block.apply_on_document(doc)
# Tokenize the sentence using a simple whitespace tokenizer
tokenize_block = Simple()
tokenize_block.apply_on_document(doc)
# Write the document in CoNLL-U format to a string
f = io.StringIO()
with redirect_stdout(f):
write_conllu_block = Conllu()
write_conllu_block.apply_on_document(doc)
conllu_output = f.getvalue()
print(conllu_output)
udapi --version
Debug
Known issues
breakingStarting with version 0.5.2, the `udapy` CLI script transitioned to use `console_scripts` for invocation. While largely backward compatible, custom installations or environments that relied on specific `PATH` configurations might require verification.fixAfter installation, verify the `udapy` command is available by running `udapy -h`. If `command not found` occurs, ensure your `PATH` environment variable includes the directory where pip installs scripts (e.g., `~/.local/bin/`).
affects: >=0.5.2
gotchaMany advanced processing blocks (e.g., for parsing or dependency tree transformations) rely on the `ufal.udpipe` library. This is an optional dependency and is not installed by default with `pip install udapi`.fixIf you need parsing or other `udpipe`-dependent functionality, install it explicitly: `pip install --upgrade ufal.udpipe`.
affects: All versions
gotchaUDAPI requires Python 3.9 or higher. Attempting to use it with older Python versions will result in runtime errors due to incompatible syntax or missing features.fixEnsure your Python environment is 3.9 or newer. It is recommended to use a virtual environment with the correct Python version.
affects: <0.5.0 (Python 3.6+ was previously supported, but current versions require 3.9+)
Errors
Common errors & fixes
command not found: udapy
The `udapy` command-line script, installed by `pip`, is not in your system's `PATH` environment variable. This often happens with user-specific installations (`pip install --user`) if the local bin directory isn't added to PATH.
fixAdd the pip-installed scripts directory (usually `~/.local/bin`) to your `PATH` environment variable: `export PATH="$HOME/.local/bin/:$PATH"`. You may also want to add this line to your shell's configuration file (e.g., `.bashrc` or `.zshrc`).
ModuleNotFoundError: No module named 'ufal.udpipe'
You are trying to use a `udapi` block that relies on the `ufal.udpipe` library, but `ufal.udpipe` has not been installed. It is an optional dependency.
fixInstall the `ufal.udpipe` library: `pip install --upgrade ufal.udpipe`.
SyntaxError: invalid syntax (or similar errors like IndentationError) when running `udapi` code
The Python version being used is older than the required Python 3.9. While the specific error might seem generic, it's often an underlying incompatibility with the required Python version.
fixUpgrade your Python environment to version 3.9 or newer. Use a tool like `pyenv` or create a virtual environment with the correct Python version.
Upgrade
Version history
0.5.2latest on PyPI · released Mar 16, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or higher.
ufal.udpipeoptionalOptional: Needed for parsing functionality (e.g., `udapi.block.udpipe.udpipe` blocks). Not required for basic reading/writing/transformation.