SwanLab: AI Training Experiment Tracker with Cloud and Self-Hosted Modes

What SwanLab Tracks and Why Experiment Records Matter

Training a machine learning model generates a stream of metrics: loss curves, validation accuracy, learning rate schedules, and hardware utilization numbers. Keeping those records organized across dozens of experiments, comparing hyperparameter variants, and sharing results with teammates are problems that grow quickly as team size and experiment volume increase.

SwanLab addresses this by providing a Python library that intercepts experiment data as training runs and stores it in a structured database, either in the cloud at swanlab.cn or in a self-hosted instance. The library exposes swanlab.init() to start a run and swanlab.log() to record metrics. Logged data appears in the web dashboard in real time.

The project is built by SwanHubX and released under the Apache-2.0 license. Python 3.9 through 3.14 is supported, as confirmed by the pyproject.toml classifiers. The most recent release at the time of the last push (2026-09-24) was v0.10.1, released on 2026-09-22.

Cloud Mode and Self-Hosted Deployment Options

SwanLab offers two deployment modes. The cloud version is hosted at swanlab.cn and requires an account. Users log into the platform, receive an API key, and point the SDK at the cloud endpoint. The dashboard is accessible from any browser and supports sharing projects via link or QR code.

The self-hosted version runs on a private server or a Kubernetes cluster. The Kubernetes deployment documentation, linked in the README changelog for the 2025.12.15 update, includes a Prometheus and Grafana monitoring stack for production observability. The README also references a Prometheus + Grafana scheme for Kubernetes deployed in the 2026.06.16 update.

For local development without a network connection, the project supports storing complete experiment log files on disk and uploading them later with `swanlab sync`. The 2025.06.08 changelog entry documents this local storage and sync path, including improved handling for training crashes where logs may be incomplete.

The cloud and self-hosted modes share the same Python SDK and dashboard. Teams that start on the cloud and later need a private instance can migrate without changing their instrumentation code.

Installing SwanLab and Starting an Experiment

The package is named swanlab on PyPI, as confirmed by the pyproject.toml file. Install it with:

pip install swanlab

The SDK entry points are swanlab.init(), which starts a new experiment run, and swanlab.log(), which records a dictionary of metric values at each step. Additional data types are available for images, video, audio, text, and molecular structures through the swanlab.Image, swanlab.Video, swanlab.Text, and swanlab.Molecule classes documented at docs.swanlab.cn.

For development setup of the SwanLab codebase itself, the Makefile init target runs:

uv sync --all-extras
pre-commit install

This installs all optional dependencies and configures pre-commit hooks. This is the contributor setup path, not the user install path.

The swanlab.Settings class, introduced in the 2025.03.30 changelog update, provides more granular control over SDK behavior including security measures for hiding API keys in logged run commands. The swanlab.Api class, released as swanlab.OpenApi earlier and promoted to swanlab.Api as a stable interface in the 2026.02.06 update, provides programmatic access to experiment data outside of training code.

Hardware Monitoring Across GPU Vendors

SwanLab monitors hardware utilization during training without requiring separate configuration. The SDK instruments the process and records GPU and CPU metrics alongside the training metrics in the same experiment run.

The supported hardware list covers a broad range of accelerators. NVIDIA GPUs are monitored through nvidia-ml-py, which is listed as a direct dependency in pyproject.toml. AMD ROCm support was added in the 2026.01.02 changelog update alongside support for Iluvatar (Tianshu GPU). Previous changelog entries cover Haiguang DCU (2025.06.08), Muxia GPU (2025.06.01), Cambricon MLU (2025.03.30), and Kunlun XPU (2025.04.23).

For teams running on Chinese-designed accelerators, this breadth of hardware support is directly relevant. Most comparable tracking tools support NVIDIA primarily, with AMD as a secondary case and limited or no coverage of domestic Chinese accelerators.

The hardware metrics appear in the same dashboard as training metrics, visible in real time during training runs. The chart for hardware statistics is a separate view from the experiment chart view.

Framework Integrations: From Transformers to PaddleNLP

SwanLab integrates with ML frameworks by providing callback classes or by being directly integrated into the framework's training loop. The README and changelog document over 50 integrations.

Hugging Face Transformers integration was accepted into Transformers version 4.50.0 (PR #36433), meaning SwanLab logging is available through the standard TrainerCallback mechanism as of that Transformers release. The accelerate integration was merged into Hugging Face accelerate (PR #3605), covering distributed training. verl (a reinforcement learning framework), LLaMA Factory, ms-swift, Ultralytics, MMEngine, Keras, ray, PaddleNLP, NVIDIA NeMo RL, MLX-LM, and ROLL are documented integrations in the changelog.

For frameworks not in this list, the swanlab.init() and swanlab.log() approach works as a manual integration: call init at the start of training, call log at each step with the metrics dictionary, and call swanlab.finish() at the end. The SDK does not require a callback hook.

For multi-process training, the parallel mode added in the 2026.03.19 update supports recording metrics from multiple processes into a single experiment simultaneously. For distributed training across nodes, the accelerate and ray integrations handle coordination.

How SwanLab Compares to Weights and Biases

Weights and Biases (W&B) is the most widely known commercial experiment tracking tool. It offers a hosted platform, team collaboration, artifact storage, and a Python SDK with a similar init/log interface. It is closed source and requires a W&B account for all but its local mode.

SwanLab's differences are practical. First, Apache-2.0 licensing means the self-hosted version can be run in a commercial environment without a software agreement. W&B's self-hosted option carries a commercial license. Second, SwanLab documents explicit support for Chinese-designed GPUs (Haiguang DCU, Cambricon MLU, Iluvatar, Kunlun XPU, Muxia), which W&B does not specifically document. Third, SwanLab's cloud version is hosted in China at swanlab.cn, which may have better latency for mainland China users than W&B's US-hosted infrastructure.

The trade-off is ecosystem maturity. W&B has a larger user base and a longer track record. Its artifact and model registry features, sweep integration, and reports functionality are more developed. Teams that are already invested in W&B tooling have no strong migration reason unless data residency or hardware coverage is a constraint.

Maintenance, License, and Release Cadence

SwanLab follows a rapid release cadence. The changelog covers updates from 2025 through September 2026, with multiple releases per month during active development periods. The v0.10.0 release was on 2026-09-01, and v0.10.1 followed on 2026-09-22. The last push to the repository was on 2026-09-24.

The Apache-2.0 license permits unrestricted commercial use, modification, and distribution without requiring source disclosure of derivatives. This is a permissive license without copyleft conditions.

The pyproject.toml classifiers list the package as Development Status :: 3 - Alpha, which is a formal signal that the API is not yet considered stable. Teams that rely on swanlab.init() and swanlab.log() for basic experiment tracking will find those interfaces stable in practice, but specific parameters, data type APIs, and configuration options have changed between releases as shown by the changelog.

The project publishes documentation at docs.swanlab.cn and maintains a WeChat community. The repository includes a SECURITY.md and a CODE_OF_CONDUCT.md, confirming that standard community governance documents are in place.

Editorial conclusion

SwanLab suits machine learning teams that run experiments regularly and need a shared dashboard for comparing runs, tracking hardware utilization, and analyzing training curves. The cloud version at swanlab.cn handles most use cases out of the box. Teams with data residency requirements or who want to avoid cloud dependencies have a supported self-hosted path, including Kubernetes deployment with Prometheus and Grafana monitoring. The Apache-2.0 license permits commercial use without restriction. Python 3.9 through 3.14 is supported. Teams using PyTorch, Hugging Face Transformers, or any of the documented integrations will have working callbacks available; teams on other frameworks should check docs.swanlab.cn for the current integration list before committing.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. SwanHubX/SwanLab on GitHub