GiNZA: a Japanese NLP layer that plugs into spaCy

GiNZA registers itself as spaCy factories, not as a rival parser

The architecture is the first thing to understand, and it explains most of the install instructions that follow. GiNZA does not replace spaCy. It plugs into it, and the packaging shows exactly how. The setup.py entry_points section registers three things under the spacy_factories key and two more under console_scripts:

    entry_points={
        "spacy_factories": [
            "bunsetu_recognizer = ginza:make_bunsetu_recognizer",
            "compound_splitter = ginza:make_compound_splitter",
            "disable_sentencizer = ginza:disable_sentencizer",
        ],
        "console_scripts": [
            "ginza = ginza.command_line:main_ginza",
            "ginzame = ginza.command_line:main_ginzame",
        ],
    },

So the package contributes a sentence recognizer that works in bunsetsu units rather than plain sentences, a compound splitter, and a component that disables spaCy's own sentencizer, plus two command line programs. The underlying tokenizer is SudachiPy, pinned in setup.py as SudachiPy>=0.6.11,<0.7.0 with SudachiDict-core>=20210802, and spaCy is required at spacy>=3.8.16,<4.0.0. The language model itself lives in a separate package, which is why installing GiNZA alone does not give you a parser.

The output format follows the Universal Dependencies convention, and the console tool prints CoNLL-U syntactic annotation with Japanese morphological fields, reading forms and named entity labels alongside the dependency columns. The parsing models come from a joint research project between Recruit Co., Ltd. and the National Institute for Japanese Language and Linguistics, so the training data provenance sits outside the repository itself.

Python 3.10 is the floor from GiNZA 5.3.0, and the docs say so loudly

The README opens with a warning aimed straight at upgraders: read the breaking changes before you upgrade GiNZA. The runtime environment changed at version 5.3.0, which was released on 2026-09-30, and from that version the requirement is Python 3.10 or later. The project recommends Python 3.12 because the dependency install is simpler and the throughput is higher. It also advises against Anaconda environments, on the grounds that the pip install step may not work properly there.

setup.py encodes the same floor, with python_requires set to >=3.10 and the version string at 5.3.0. The dependency list in requirements.txt matches the install_requires block in setup.py, with one extra environment marker: thinc-apple-ops is pulled in when the platform is darwin, the machine is arm64, and the Python version is below 3.13.

That marker is the whole Apple Silicon story in one line, and it has a sharp edge. thinc-apple-ops is not supported in Python 3.13 and later, so the hardware accelerated path on Mac silently disappears on a newer interpreter even though the package still installs.

The GitHub releases tell a steadier story than the README alone suggests: v5.3.0 on 2026-09-30, v5.2.1 on 2026-09-01, and before that v5.2.0 from 2024-03-30. The last push was on 2026-09-30, so the repository is being worked on actively rather than sitting still.

Three model packages, and the transformer ones want 16GB

You choose a model by choosing a package, and the choice is mostly about memory and speed. The standard model is installed with one command, and GiNZA comes along with it:

$ pip install -U ja_ginza

The transformer based models are separate packages. The README names both ja_ginza_electra and ja_ginza_bert_large, and installing either one pulls in GiNZA and the related Transformers libraries:

$ pip install -U ja_ginza_electra

$ pip install -U ja_ginza_bert_large

The warning attached to the transformer path is blunt: running the Transformers model requires at least 16GB of memory, and if you do not have that, the standard model is the fallback.

Two operational details follow from how the model packages are built. The package you install does not include the large transformer models or tokenizers themselves. Those files are downloaded from Hugging Face Hub on the first run and cached locally for later runs, so the first run of a transformers model takes from several seconds to tens of seconds while initialisation happens. In an air gapped or bandwidth constrained environment, that first run is the one that needs planning, and the README does not document an offline mode for it.

The console tool is how you see any of this working. Running it and typing Japanese text returns the CoNLL-U syntactic annotation for the sentence.

ginzame gives you a MeCab style listing with a stubbed pronunciation field

Two command line programs come with the package, and they answer different questions. The ginza command parses and prints a dependency tree. The ginzame command does tokenization in the style of MeCab, and the README is precise about how the output differs: the format is almost the same as mecab, but the last pronunciation field is always '*'.

That single detail matters if you are planning to reuse ginzame output in a pipeline that expects the MeCab field layout, because a column that is structurally present but never populated will need handling on your side rather than being treated as real pronunciation data.

The console command also has device selection, which is the mechanism behind the GPU acceleration story. The -g option takes a device number, and specifying -1 disables GPU acceleration entirely:

$ ginza -g 0

When you run the command without -g and acceleration is active, the initialisation log tells you which mechanism is in play. For a GPU:

$ ginza
GPU #0 enabled

And for the standard model on Apple Silicon:

$ ginza
thinc-apple-ops enabled

That second line is worth remembering because it tells you which of the two acceleration paths you are on. The ginza command enables GPU acceleration by default if a GPU is available, so on a desktop with a discrete card you get the GPU path automatically, and on a Mac you get thinc-apple-ops for the standard model.

CUDA extras are per version, and the Mac speedups are model specific

NVIDIA acceleration on Linux is an install time decision, not a runtime one. You need CUDA installed on the machine, the CUDA library path added to LD_LIBRARY_PATH in the form `export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH`, and then the ginza package installed with the extras matching your CUDA version. The extras are named cuda11x, cuda12x and cuda13x, and the install commands are `$ pip install ginza[cuda11x]`, `$ pip install ginza[cuda12x]` and `$ pip install ginza[cuda13x]` for CUDA 11.x, 12.x and 13.x respectively.

Those three extras names match the extras_require block in setup.py, where cuda11x maps to cupy-cuda11x, cuda12x to cupy-cuda12x and cuda13x to cupy-cuda13x. A version mismatch between your driver and the extra is the failure mode to plan around, and the README does not describe a fallback that degrades to CPU automatically.

On Apple Silicon the numbers differ per model, and the difference is a property of the implementation rather than of the hardware. For the standard ja_ginza model, acceleration through thinc-apple-ops is documented as 2.6 times for Python 3.10 to 3.11 and 5.2 times for Python 3.12, measured on a MacBook Pro M4 Max with 128GB. For ja_ginza_bert_large, acceleration through torch.backends.mps is documented as 1.3 times for Python 3.10 to 3.13, on the same machine. The first path supports Python 3.10 to 3.12 only, the second supports 3.10 to 3.13, with some compilation environments needed to build dependent libraries under Python 3.14.

Two different backends, two different multipliers, and a version ceiling on each. That is the kind of detail that decides whether you pick Python 3.12 or 3.13 on a Mac, and it is not visible from the package list alone.

Where GiNZA is the wrong tool

GiNZA is a poor fit when the memory budget is tight or the dependency list has to stay small. The install brings in spaCy, SudachiPy, a Sudachi dictionary, and for a transformer model the whole Transformers stack plus a first run download of model files and tokenizers from Hugging Face Hub. For a service that tokenises short strings in a request path, that is a lot of machinery for what spaCy already does for other languages.

It is also the wrong choice if you need a single pipeline spanning English and Japanese with one model and one set of resources. GiNZA is Japanese only, and its models are separate packages rather than a single multilingual checkpoint, so a bilingual pipeline means two model stacks.

The GPU story is another place to look before committing. On a Mac, the accelerated path depends on the interpreter version, and on Linux it depends on picking the right extras and having a matching CUDA install. The README treats acceleration as something you configure deliberately rather than something that happens to you.

Finally, the version 5.3.0 release carries breaking changes, and the README puts its breaking changes notice above everything else on the page. That is the shape of a project with a real compatibility surface, which is a good thing to know before a version bump lands on a deployment you did not choose the timing of.

Editorial conclusion

GiNZA is the right choice for a team that already builds spaCy pipelines and needs Japanese tokenization, dependency parsing and CoNLL-U output without writing a Japanese model stack from scratch, and the wrong choice for a project that wants a light dependency footprint or a single English and Japanese pipeline with one memory budget. Before you commit, check that pip install -U ja_ginza works with your Python version, since the runtime floor moved to 3.10 at GiNZA 5.3.0, and confirm that your machine has 16GB of memory if you plan to run ja_ginza_electra or ja_ginza_bert_large rather than the standard ja_ginza model.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. megagonlabs/ginza on GitHub
4. README
5. Releases