# dict_uk expands a Ukrainian word list into every inflected form

> dict_uk is the project behind VESUM, the large electronic dictionary of Ukrainian, and it works by applying affix rules from data/affix to every entry in data/dict to generate all possible word forms with part of speech tags. The build is a Gradle task that needs a JDK and about 5 GB of memory, and the dictionary data itself is published under a non-commercial licence.

**brown-uk/dict_uk** — Project to generate POS tag dictionary for Ukrainian language

- Repository: https://github.com/brown-uk/dict_uk
- Stars: 633 · Forks: 75
- Language: Groovy
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/brown-uk-dict-uk

## Affix rules turn a lemma list into every word form

The mechanism is generative rather than curated. For all files in data/dict the project generates all possible word forms with POS tags by using affix rules from files in data/affix.

That split is the heart of the design. The dictionary side holds the base words and their paradigms, and the affix side holds the rules that say what a Ukrainian noun, verb, adjective or participle does to its stem. Change a rule and every affected word in the dictionary is re-expanded, which is a very different maintenance model from maintaining a table of every inflected form by hand.

The output is a set of flat text files under out/. The dictionary in visual, indented format grouped by lemmas is written for review, analysis and conversion, the flat table version is used for preparing the morfologik dictionary consumed by LanguageTool, and there are separate lists of all unique known words, of the words considered valid for spelling, and of the unique lemmas.

The project has two uses. The first is generating all possible word forms for the words already in the dictionary. The second is generating forms for arbitrary words in an interactive mode, which the documentation covers separately in doc/interactive_mode.md, and which is the more interesting capability for anyone building a tagger.

## The dictionary holds more than tags

The description of the dictionary contents lists more than word forms. Alongside the words, their paradigms and their corresponding tags, the dictionary carries other information.

There are additional tags such as slang, rare and bad, which is how a dictionary can mark a word as colloquial, uncommon or unsuitable without removing it. There are suggested replacements for misspellings, which is the kind of data a spell checker can consume directly. There is a link between the base and comparative forms of adjectives, and the management of adjective cases.

That last part matters for a morphological tool. Tagging a form only tells you what a word is; linking a comparative to its base and tracking how a case behaves tells you how the word relates to the rest of the sentence, and that is the difference between a tagset and a usable dictionary.

The project is the Large Electronic Dictionary of Ukrainian, known by its Ukrainian abbreviation VESUM, and the readme asks users to cite the web version of VESUM with the authors Andriy Rysin and Vasyl Starko, the team of BrUK, version 6.7.8, spanning 2005 to 2026, at the site vesum.nlp.net.ua.

## One Gradle task produces the dictionary files

Running the project is a single command in the project directory:

    ./gradlew expand

and on Windows there is a shell script, bin/expand_win.sh, which the readme lists as the alternative. The Gradle wrapper is checked in, since gradlew and gradlew.bat are both in the repository root, so no local Gradle installation is needed.

The output files are the contract, and the readme lists them precisely. out/dict_corp_vis.txt holds the dictionary in a visual, indented format for review, analysis or conversion. out/dict_corp_lt.txt is the flat table format, and it is the file from which the morfologik dictionary used by LanguageTool is generated. out/words.txt is the list of all unique known words, out/words_spell.txt is the subset valid for spelling, and out/lemmas.txt is the list of unique lemmas.

The distinction between words.txt and words_spell.txt is the one to understand. A dictionary that knows a word is not the same as a dictionary that considers it correctly spelled, and a spell checker needs the second list, not the first.

The repository also carries a publish.sh, a do_all.sh, a VERSION file and a dev/ directory, which together suggest a scripted pipeline from expansion through to distribution of the derived dictionaries.

## The build wants a JDK and about 5 GB of memory

The stated requirements are short. You need java with a JDK of 11 or later, and about 5 GB of free memory. On Windows the readme also asks for git bash to be installed and running.

The memory figure is the one to notice, because it scales with the size of the dictionary rather than with the size of your code. The expansion is essentially a large graph walk over a big word list, and it holds a lot of form data at once. This is a batch job, not something to run on a small machine or inside a constrained container, and it is also why the interactive mode exists as a separate path for generating forms for a handful of words.

The repository layout shows the shape of the pipeline. The data/ directory holds the dictionary and the affix rules, the src/ directory holds the code, which the project listing records as Groovy, build.gradle drives the Gradle build, and there are separate directories for the derived distributions, the documentation and the tests. The gradle.properties file at the top level is where the memory settings for the build would live.

## The Docker build runs the expansion in a Ukrainian locale

For a machine that cannot spare 5 GB or cannot install a JDK, the repository ships a Dockerfile that performs the whole expansion as part of the image build:

```dockerfile
FROM ubuntu:24.04

RUN apt update
RUN apt install -y openjdk-21-jdk-headless locales

ADD . /src
WORKDIR /src

RUN locale-gen uk_UA.UTF-8 && update-locale LANG=uk_UA.UTF-8
# RUN locale -a
# RUN LC_ALL=uk_UA.UTF-8 ls -al
RUN mkdir -p out/stats
RUN LC_ALL=uk_UA.UTF-8 ./gradlew expand
```

Two details in that file are the interesting part. The image installs the locales package and generates a Ukrainian UTF-8 locale, and the Gradle run is executed with LC_ALL set to it. Ukrainian has grammatical cases and inflections that string handling tools handle differently depending on locale, and running the expansion under a Ukrainian locale is how the project avoids inconsistencies between the generated data and the expectations of the tools that consume it. There is also a commented out locale -a, which is the kind of debugging step left in a working Dockerfile.

The readme documents the run cycle, building the image, starting a container, copying the out directory out of it, fixing ownership of the copied files, and stopping the container:

```bash
sudo docker build -t brown-uk/dict_uk .
sudo docker run -d --name dict_uk brown-uk/dict_uk /bin/bash
sudo docker cp dict_uk:/src/out/ ./out
sudo chown -R $USER: ./out
sudo docker stop dict_uk
```

The copy and the chown step are there because the files are written inside the container as root, so this pattern is a way to get the results onto the host without running the expansion natively.

## Two licences, and the data one is not permissive

The licensing is split, and the split is the first thing to check before using anything from this project.

The dictionary data are distributed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Licence. The software is distributed under GPL 3.0 or above. The readme also notes that the derivative projects have their own licences, and that the content in this project is allowed to be used in the Mozilla Voice Ukrainian site and in the Common Voice sentence collector according to their own licences.

The practical consequence is that the code is permissively usable in the sense of being GPL, but the data is not free for commercial use. A company building a commercial Ukrainian language product cannot take the word list as it stands, because the non-commercial clause and the share-alike requirement both apply to the data. That is a licensing fact about the data, not a judgement about the project, and it is why the derived dictionaries are shipped separately with their own terms.

The copyright line names Andriy Rysin, Vasyl Starko and the BrUK team, and the licences are written to be read before you build, since a data pipeline that emits a word list that later ends up in a paid product is exactly the situation the non-commercial clause exists to prevent.

## Four derived dictionaries ship from the same source

The readme lists the derivative projects, each with its own README under the distr/ directory. There are morfologik dictionaries, hunspell dictionaries, Firefox dictionaries and LibreOffice.org dictionaries.

Each of those is a different consumption path for the same generated data. The morfologik format is the one LanguageTool uses, and the readme notes that the flat dictionary file is the input for preparing it. The hunspell format serves spell checkers in the desktop world, and the Firefox and LibreOffice dictionaries are the same idea applied to a browser and to an office suite.

That list is the clearest argument for the project. This is not a research dataset that ends at a paper, it is the upstream source that four widely used pieces of software consume, and the fact that they need separate licences is the practical reminder that redistribution terms differ per target.

The documentation directory holds the longer form material, with the interactive mode covered in its own file, and the readme points readers there for more detail than the summary pages give.

## Versioning, releases and how to cite VESUM

The release history shows a steady line. The tags include v6.8.6 on 2026-09-19, v6.8.5 on 2026-08-23 and v6.8.0 on 2026-04-23, and the last push was on 2026-09-22 with the repository not archived. The numbers are the dictionary version rather than a code version, which is the right convention for a data project where the artefact people consume is the data.

The citation guidance is explicit and worth following exactly. The readme asks that the web version of VESUM be cited as Rysin A. and Starko V., Large Electronic Dictionary of Ukrainian, version 6.7.8, 2005 to 2026, with the URL vesum.nlp.net.ua, and it gives the English form of the same reference.

That reference is to version 6.7.8 while the current tags are in the 6.8 line, which tells you the citation is not auto generated and that a paper or a documentation page should name the version it actually used. The VERSION file at the repository root is the place to check the number that your build produced.

The build system is Gradle with a checked in wrapper, and the repository also carries a bin/ directory with the Windows script, a publish.sh for releasing the derived artefacts, and a Dockerfile for the containerised build described earlier.

## Conclusion

Adopt dict_uk if you need a Ukrainian morphological dictionary with part of speech tags for a spell checker, a morphology tool or a language technology project, since the generation rules and the word list are both in the repository and the outputs feed the morfologik, hunspell, Firefox and LibreOffice dictionaries. Skip it if your use is commercial, because the dictionary data is under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 while only the software is GPL 3.0, and skip it if you cannot spare a JDK 11 or later plus roughly 5 GB of memory for a build. Before you use it, read the doc/ folder, run ./gradlew expand and compare out/lemmas.txt with the version of VESUM you intended to cite, and check the licences of the derivative project you actually need.

## FAQ

### What is the dict_uk project?

It is the project to generate a POS tag dictionary for the Ukrainian language, known as VESUM, the Large Electronic Dictionary of Ukrainian. For all files in data/dict it generates all possible word forms with POS tags using affix rules from data/affix.

### How do I build the dict_uk dictionary?

Install java with a JDK of 11 or later, clone the project, enter the project directory and run ./gradlew expand. On Windows there is an alternative script, bin/expand_win.sh, and the build needs about 5 GB of free memory.

### What files does the dict_uk build produce?

It writes out/dict_corp_vis.txt in an indented visual format grouped by lemmas, out/dict_corp_lt.txt in flat format for preparing the morfologik dictionary used by LanguageTool, out/words.txt with all unique known words, out/words_spell.txt with the words valid for spelling, and out/lemmas.txt with the unique lemmas.

### Can dict_uk be used for commercial products?

The dictionary data are distributed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0, so the data itself carries non-commercial and share-alike terms, while the software is under GPL 3.0 or above. The derivative projects in distr/ have their own licences, so check the terms of the specific dictionary you plan to use.

### Which Ukrainian dictionaries are built from this project?

The readme lists morfologik dictionaries, hunspell dictionaries, Firefox dictionaries and LibreOffice.org dictionaries as derivative projects, each with its own README under the distr/ directory. The morfologik format is the one consumed by LanguageTool.

### Why does the dict_uk Docker build set a Ukrainian locale?

The Dockerfile installs the locales package, generates the uk_UA.UTF-8 locale and runs ./gradlew expand with LC_ALL set to it, so the expansion happens under a Ukrainian locale rather than the image default. The readme also documents copying the out directory out of the container and fixing its ownership.

## Sources

- [brown-uk/dict_uk on GitHub](https://github.com/brown-uk/dict_uk)
- [Issues](https://github.com/brown-uk/dict_uk/issues)
- [License: GPL-3.0](https://github.com/brown-uk/dict_uk/blob/master/LICENSE)
- [README](https://github.com/brown-uk/dict_uk/blob/master/README.md)
- [Releases](https://github.com/brown-uk/dict_uk/releases)

---

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