{"id":1032,"library":"thinc","title":"Thinc","description":"Thinc is a lightweight deep learning library from the makers of spaCy and Prodigy, offering a type-checked, functional-programming API for composing models. It emphasizes composition over inheritance and supports wrapping layers from other frameworks like PyTorch, TensorFlow, and MXNet, allowing for flexible model development. Thinc is actively maintained with frequent releases to support new Python versions and address bug fixes.","status":"active","version":"9.1.1","language":"python","source_language":"en","source_url":"https://github.com/explosion/thinc","tags":["deep learning","neural networks","nlp","functional programming","machine learning","framework"],"install":[{"cmd":"pip install thinc","lang":"bash","label":"Install Thinc"}],"dependencies":[{"reason":"Core numerical operations. Thinc aims for compatibility across numpy v1 and v2, though specific builds might target v2.0.","package":"numpy","optional":false},{"reason":"Used for configuration parsing and validation. Requires >=2.0 for Python 3.13+ support, with a significant internal migration from v1 to v2.","package":"Pydantic","optional":false},{"reason":"Optimized BLAS library for efficient numerical operations. Versioning has been sensitive due to Windows-specific crashes.","package":"blis","optional":false},{"reason":"Configuration system, Thinc supports confection v1.","package":"confection","optional":false},{"reason":"Optional for GPU support (NVIDIA CUDA).","package":"cupy","optional":true},{"reason":"Optional for PyTorch integration and wrapping PyTorch models.","package":"torch","optional":true},{"reason":"Optional for TensorFlow integration and wrapping TensorFlow models.","package":"tensorflow","optional":true},{"reason":"Optional for MXNet integration and wrapping MXNet models.","package":"mxnet","optional":true}],"imports":[{"symbol":"Model","correct":"from thinc.api import Model"},{"symbol":"chain","correct":"from thinc.api import chain"},{"symbol":"Relu","correct":"from thinc.api import Relu"},{"symbol":"Softmax","correct":"from thinc.api import Softmax"},{"symbol":"Config","correct":"from thinc.api import Config"},{"symbol":"registry","correct":"from thinc.api import registry"}],"quickstart":{"code":"import thinc.api as api\n\n# Define a simple feed-forward model using combinators\nn_hidden = 128\n\nwith api.Model.define_operators({ \">>\" : api.chain }):\n    model = api.Relu(nO=n_hidden) >> api.Relu(nO=n_hidden) >> api.Softmax()\n\n# Initialize the model (e.g., with dummy data for shape inference)\n# In a real scenario, this would be done with actual data or explicit nI/nO.\n# For demonstration, we'll manually set nI if it's not inferred.\nif model.init_no_grad is None:\n    model.init_no_grad = lambda X, Y: (X, Y)\n\n# Example: If your model requires an input dimension, set it manually or via dummy data\n# For this simple model, `nI` must be set if not inferred from `X` during init.\n# Let's assume an input dimension of 784 (e.g., for MNIST flattened images)\nmodel.set_dim(\"nI\", 784)\nmodel.initialize() # Initialize parameters\n\nprint(f\"Model: {model.name}\")\nprint(f\"Input dimension (nI): {model.get_dim('nI')}\")\nprint(f\"Output dimension (nO): {model.get_dim('nO')}\")\nprint(f\"Number of parameters: {model.to_bytes().nbytes} bytes\")\n\n# Simulate a forward pass (requires numpy for dummy data)\nimport numpy\nX_dummy = numpy.random.rand(10, model.get_dim('nI')).astype('f')\nY_dummy, callback = model(X_dummy, is_train=False)\nprint(f\"Output shape: {Y_dummy.shape}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to version 3.10 or higher.","message":"Thinc dropped support for Python 3.9 in recent versions (e.g., v8.3.7). Ensure your Python environment is 3.10 or newer.","severity":"breaking","affected_versions":">=8.3.7"},{"fix":"Ensure model architecture is consistent across serialization/deserialization. Avoid modifying `model.layers` or similar node structures within the `init` function.","message":"`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.","severity":"breaking","affected_versions":"All versions"},{"fix":"When implementing custom loss functions or interpreting gradients, remember that `get_grad` operates on logits. Consult the Thinc documentation for loss calculator implementations.","message":"The `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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Review 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+.","message":"Thinc'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.","severity":"breaking","affected_versions":">=8.3.6 (for Pydantic >= 2.0)"},{"fix":"Ensure `blinc` is installed via Thinc's provided wheels or a known-good configuration. Report crashes to the Thinc repository with full system details.","message":"There 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Pay close attention to the argument order (`nO`, `nI`) when defining Thinc layers or wrapping models from other frameworks to avoid dimension mismatches.","message":"Thinc'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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"A 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update 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.","message":"The `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`.","severity":"breaking","affected_versions":">=8.1.0"},{"fix":"Ensure 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`.","message":"Thinc 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.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T22:50:17.330Z","next_check":"2026-06-27T00:00:00.000Z","problems":[],"ecosystem":"pypi","meta_description":null,"install_score":90,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"9.1.1","cli_name":"thinc","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.71,"mem_mb":20,"disk_size":"156.2M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.89,"mem_mb":20,"disk_size":"155.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":7.7,"import_time_s":0.57,"mem_mb":20,"disk_size":"146M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.56,"mem_mb":20,"disk_size":"146M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1,"mem_mb":21.9,"disk_size":"167.1M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.13,"mem_mb":21.9,"disk_size":"166.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.8,"import_time_s":0.87,"mem_mb":21.9,"disk_size":"157M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.9,"mem_mb":21.9,"disk_size":"156M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.2,"mem_mb":21.7,"disk_size":"163.7M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.27,"mem_mb":21.7,"disk_size":"163.3M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.7,"import_time_s":1.27,"mem_mb":21.7,"disk_size":"153M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.28,"mem_mb":21.7,"disk_size":"153M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":11.2,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.62,"mem_mb":18.9,"disk_size":"164.1M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.72,"mem_mb":18.9,"disk_size":"163.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":8.9,"import_time_s":0.69,"mem_mb":18.9,"disk_size":"156M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.63,"mem_mb":18.9,"disk_size":"156M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}