Install & Compatibility
Where this runs
tested against v1.0.5 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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"
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" }
# ]
Debug
Known issues
breakingStarting 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.fixUpdate 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" }
]
``` affects: >=1.0.5 (WandbLogger.v5), >=1.0.4 (ClearMLLogger.v2), >=1.0.3 (MLflowLogger.v2)
gotchaThe `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.fixPrefer `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`.
affects: All
gotchaEach 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.fixEnsure 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.
affects: All
gotchaWhen 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.fixSet 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`.
affects: All
gotchaThe `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.fixBe 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.
affects: >=1.0.3
breakingThe `@loggers = "spacy.WandbLogger.v5"` syntax is part of spaCy's configuration file format (`config.cfg`) and cannot be used directly within a Python script. Attempting to use it in a `.py` file will result in a `SyntaxError`.fixEnsure that spaCy configuration settings, especially those using the `@` registry syntax, are placed in a `config.cfg` file and passed to spaCy commands (e.g., `spacy train config.cfg`), not directly embedded in Python code intended for execution.
affects: All
breakingThe `@loggers = ...` syntax is specific to spaCy's `config.cfg` files and is not valid Python code. If you encounter a `SyntaxError` when attempting to define a logger, ensure that the configuration is being loaded by spaCy (e.g., via `python -m spacy train config.cfg`) and not executed directly as a Python script.fixEnsure your spaCy configuration is placed in a `.cfg` or `.ini` file and passed to `python -m spacy train` or similar spaCy command that handles config parsing, rather than being part of a Python script executed directly.
affects: All
Upgrade
Version history
1.0.5latest on PyPI · released Sep 11, 2023
Audit
Dependencies
spacyrequiredCore dependency for spaCy training and pipelines.
wandboptionalRequired for using `spacy.WandbLogger`.
mlflowoptionalRequired for using `spacy.MLflowLogger`.
clearmloptionalRequired for using `spacy.ClearMLLogger`.
torchoptionalRequired for using `spacy.PyTorchLogger`.
cupyoptionalRequired for using `spacy.CupyLogger`.