spaCy Loggers

1.0.5 · active · verified Mon Apr 06

spacy-loggers is a Python library that provides logging utilities for spaCy v3.2 and newer, allowing integration with various MLOps tools and machine learning frameworks. It currently supports Weights & Biases, MLflow, ClearML, PyTorch, and CuPy, offering a way to track training metrics and model artifacts independently from the core spaCy library. The current version is 1.0.5, with an active release cadence that regularly introduces new loggers and updates existing ones.

Warnings

breaking Starting with `spacy.WandbLogger.v5`, `spacy.MLflowLogger.v2`, and `spacy.ClearMLLogger.v2`, these loggers no longer automatically call the default console logger. If you want console output alongside these, you must explicitly use `spacy.ChainLogger.v1` and include `spacy.ConsoleLogger.v2` in the chain.
Fix: Update your `config.cfg` to use `spacy.ChainLogger.v1` and explicitly include `spacy.ConsoleLogger.v2` in the `loggers` list, for example: ```ini [training.logger] @loggers = "spacy.ChainLogger.v1" loggers = [ { "@loggers": "spacy.ConsoleLogger.v2" }, { "@loggers": "spacy.WandbLogger.v5", "project_name": "my_project" } ] ```
gotcha The `prodigy train` command (from Prodigy, a related annotation tool) overrides logger settings in its configuration. Therefore, `spacy-loggers` integrations might not function as expected when training via `prodigy train`. It is recommended to use `python -m spacy train` with your `config.cfg` for full logger functionality.
Fix: Prefer `python -m spacy train config.cfg` for training pipelines when using `spacy-loggers` for experiment tracking. If using Prodigy, consider setting up a spaCy project file to orchestrate `prodigy data-to-spacy` followed by `spacy train`.
gotcha Each external logger (Weights & Biases, MLflow, ClearML) requires its respective library to be installed separately and may need initial configuration (e.g., `pip install wandb && wandb login`, `pip install mlflow`, `pip install clearml && clearml-init`). Without these, the loggers will not function correctly.
Fix: Ensure all required external MLOps libraries are installed (`pip install spacy-loggers[<integration>]`) and configured according to their official documentation before running spaCy training with the respective logger.
gotcha When using `spacy.MLflowLogger.v2` for remote MLflow tracking, environment variables such as `MLFLOW_TRACKING_URI` must be correctly set before launching `spacy train`. Forgetting to do so may result in silent failures or local logging instead of remote.
Fix: Set required MLflow environment variables (e.g., `export MLFLOW_TRACKING_URI=http://your-mlflow-server:5000`) in your shell session or script before executing `python -m spacy train`.
gotcha The `spacy.MLflowLogger.v2`'s `log_custom_stats` parameter is intended to filter logged metrics, but it currently logs all metrics internally before applying the regex filters. This can lead to more data being logged than intended if not aware of the behavior.
Fix: Be aware that `log_custom_stats` with `MLflowLogger.v2` might log more data than strictly specified by the regexps. Review MLflow logs for unwanted metrics. For strict control, a custom logger might be needed.

Install

pip install spacy-loggers Install `spacy-loggers`
pip install spacy-loggers[wandb] spacy-loggers[mlflow] spacy-loggers[clearml] spacy-loggers[torch] spacy-loggers[cupy] Install with all optional dependencies

Imports

WandbLogger.v5
```
@loggers = "spacy.WandbLogger.v5"
```
MLflowLogger.v2
```
@loggers = "spacy.MLflowLogger.v2"
```
ClearMLLogger.v2
```
@loggers = "spacy.ClearMLLogger.v2"
```
ChainLogger.v1
```
@loggers = "spacy.ChainLogger.v1"
```
PyTorchLogger.v1
```
@loggers = "spacy.PyTorchLogger.v1"
```
CupyLogger.v1
```
@loggers = "spacy.CupyLogger.v1"
```

Quickstart

spaCy loggers are typically configured within the `config.cfg` file used for `spacy train`. The `@loggers` key under `[training.logger]` specifies which logger to use. Ensure the respective external logging library (e.g., `wandb`) is installed and configured (e.g., `wandb login`).

# Example config.cfg snippet for Weights & Biases logging
# This file is typically used with `python -m spacy train config.cfg`

[training.logger]
@loggers = "spacy.WandbLogger.v5"
project_name = "my_spacy_project"
remove_config_values = ["paths.train", "paths.dev"]

# To combine with console logging (required for v5+ if console output is desired)
# [training.logger]
# @loggers = "spacy.ChainLogger.v1"
# loggers = [
#   { "@loggers": "spacy.ConsoleLogger.v2" },
#   { "@loggers": "spacy.WandbLogger.v5", "project_name": "my_spacy_project" }
# ]

view raw JSON →