Install & Compatibility
Where this runs
tested against v9.1.1 · 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
py 3.13
✕ build_error
✕ build_error
158MB installed
● package 158MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Model
✓ from thinc.api import Model
chain
✓ from thinc.api import chain
Relu
✓ from thinc.api import Relu
Softmax
✓ from thinc.api import Softmax
Config
✓ from thinc.api import Config
registry
✓ from thinc.api import registry
This quickstart demonstrates defining a basic feed-forward neural network using Thinc's functional API and combinators (`chain`, `Relu`, `Softmax`). It shows how to define operators, initialize a model, and perform a simulated forward pass.
import thinc.api as api
# Define a simple feed-forward model using combinators
n_hidden = 128
with api.Model.define_operators({ ">>" : api.chain }):
model = api.Relu(nO=n_hidden) >> api.Relu(nO=n_hidden) >> api.Softmax()
# Initialize the model (e.g., with dummy data for shape inference)
# In a real scenario, this would be done with actual data or explicit nI/nO.
# For demonstration, we'll manually set nI if it's not inferred.
if model.init_no_grad is None:
model.init_no_grad = lambda X, Y: (X, Y)
# Example: If your model requires an input dimension, set it manually or via dummy data
# For this simple model, `nI` must be set if not inferred from `X` during init.
# Let's assume an input dimension of 784 (e.g., for MNIST flattened images)
model.set_dim("nI", 784)
model.initialize() # Initialize parameters
print(f"Model: {model.name}")
print(f"Input dimension (nI): {model.get_dim('nI')}")
print(f"Output dimension (nO): {model.get_dim('nO')}")
print(f"Number of parameters: {model.to_bytes().nbytes} bytes")
# Simulate a forward pass (requires numpy for dummy data)
import numpy
X_dummy = numpy.random.rand(10, model.get_dim('nI')).astype('f')
Y_dummy, callback = model(X_dummy, is_train=False)
print(f"Output shape: {Y_dummy.shape}")
thinc --version
Debug
Known issues
breakingThinc dropped support for Python 3.9 in recent versions (e.g., v8.3.7). Ensure your Python environment is 3.10 or newer.fixUpgrade Python to version 3.10 or higher.
affects: >=8.3.7
breaking`Model.from_disk` (and deserialization in general) requires the model architecture to match exactly what it was serialized from. Side-effects within the `init` function of a `Model` will not be replicated during deserialization if they modify the layer's node structure.fixEnsure model architecture is consistent across serialization/deserialization. Avoid modifying `model.layers` or similar node structures within the `init` function.
affects: All versions
breakingThe `Loss.get_grad` method computes the gradient with respect to *logits* (pre-softmax outputs), not the post-softmax probabilities. While this design is for numerical stability, it can be a source of confusion if not explicitly understood.fixWhen implementing custom loss functions or interpreting gradients, remember that `get_grad` operates on logits. Consult the Thinc documentation for loss calculator implementations.
affects: All versions
breakingThinc's migration to Pydantic v2 (required for Python 3.13+) introduced breaking changes due to how Thinc's internal configuration system used Pydantic v1. While Thinc has adapted, direct interactions with Pydantic in custom Thinc components might require updates if migrating from older Thinc/Pydantic versions.fixReview Pydantic v1 to v2 migration guides, especially regarding data validation and model definitions, if you have custom code interacting with Pydantic via Thinc's config system. Ensure Pydantic >= 2.0 is installed with Python 3.13+.
affects: >=8.3.6 (for Pydantic >= 2.0)
gotchaThere have been intermittent crashes related to the `blis` package on Windows, leading to specific version pinning in Thinc releases. Users on Windows may encounter stability issues if `blis` versions are mismatched or not well-tested for their environment.fixEnsure `blinc` is installed via Thinc's provided wheels or a known-good configuration. Report crashes to the Thinc repository with full system details.
affects: All versions
gotchaThinc's built-in layers and constructors often define output dimension (`nO`) as the first argument, followed by input dimension (`nI`), which is opposite to the `in_features`, `out_features` convention in PyTorch layers.fixPay close attention to the argument order (`nO`, `nI`) when defining Thinc layers or wrapping models from other frameworks to avoid dimension mismatches.
affects: All versions
gotchaA float64 dtype mismatch in BLIS gemm operations can lead to errors. This usually indicates an incompatibility in the array types being passed to Thinc's underlying numerical backend.fixEnsure consistency in floating-point data types (e.g., use `float32` or `xp.asarray(..., dtype='f')` where `xp` is `numpy` or `cupy`) across your model and inputs, especially when working with BLIS-accelerated operations.
affects: All versions
breakingThe `Model.init_no_grad` attribute and `Model.no_grad` context manager were removed in Thinc v8.1.0. Code expecting these will encounter an `AttributeError`.fixUpdate your code to use `model.begin_update` or the `Optimizer` for managing gradient computation, as `Model.init_no_grad` and `Model.no_grad` were removed. Consult the Thinc documentation for the correct API to handle gradient context.
affects: >=8.1.0
breakingThinc requires a C/C++ compiler (like `gcc` or `g++`) to be present in the build environment, as it compiles Cython extensions during installation. This is particularly relevant in minimal environments (e.g., Alpine Linux Docker images) where build tools are not included by default.fixEnsure that build essential tools, including a C/C++ compiler, are installed in your environment. For Alpine Linux, this typically involves `apk add build-base` or similar commands. For Debian/Ubuntu, use `apt-get install build-essential`.
affects: All versions
Upgrade
Version history
9.1.1latest on PyPI · released Sep 12, 2024
Audit
Dependencies
numpyrequiredCore numerical operations. Thinc aims for compatibility across numpy v1 and v2, though specific builds might target v2.0.
PydanticrequiredUsed for configuration parsing and validation. Requires >=2.0 for Python 3.13+ support, with a significant internal migration from v1 to v2.
blisrequiredOptimized BLAS library for efficient numerical operations. Versioning has been sensitive due to Windows-specific crashes.
confectionrequiredConfiguration system, Thinc supports confection v1.
cupyoptionalOptional for GPU support (NVIDIA CUDA).
torchoptionalOptional for PyTorch integration and wrapping PyTorch models.
tensorflowoptionalOptional for TensorFlow integration and wrapping TensorFlow models.
mxnetoptionalOptional for MXNet integration and wrapping MXNet models.