swanlab

library0.8.3pypypi✓ verified 89d ago

SwanLab is a Python library for streamlined tracking and management of AI training processes. It offers experiment tracking, visualization, automatic logging, hyperparameter recording, experiment comparison, and multi-user collaboration. SwanLab supports both cloud and offline usage, integrating with over 30 mainstream AI training frameworks. The current version is 0.7.15, with frequent patch and minor releases.

ai-ml observability data

pip install swanlab

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · SWANLAB

swanlab

ai-mlpythonv0.8.3

Install

7.8s avg

Import

2726ms

Disk

69MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.8.3 · 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

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 2.935s · 67.3MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 7.8s · import 2.516s · 68MB

69MB installed

● package 69MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

swanlab

✓ import swanlab

swanlab.init

✓ swanlab.init(...)

swanlab.log

✓ swanlab.log({...})

swanlab.finish

✓ swanlab.finish()

Important to call explicitly in notebooks or long-running scripts to ensure data upload and proper run termination.

This quickstart initializes a SwanLab experiment, logs hyperparameters using `config`, and then simulates a training loop to log scalar metrics (`loss` and `accuracy`) using `swanlab.log()`. It concludes by explicitly calling `swanlab.finish()`.

import swanlab import random # Initialize a SwanLab experiment run = swanlab.init( project="my-ml-project", experiment_name="basic_training_run", config={ "learning_rate": 0.01, "epochs": 5, "batch_size": 32 } ) # Simulate a training loop for epoch in range(run.config.epochs): loss = 1.0 / (epoch + 1) + random.uniform(-0.1, 0.1) accuracy = 0.5 + (epoch / run.config.epochs) * 0.4 + random.uniform(-0.05, 0.05) # Log metrics swanlab.log({"loss": loss, "accuracy": accuracy}) print(f"Epoch {epoch+1}, Loss: {loss:.4f}, Accuracy: {accuracy:.4f}") # Finish the experiment explicitly (optional in most scripts, but good practice) swanlab.finish()

swanlab --version

Debug

Known issues

gotchaWhen running SwanLab experiments within subprocesses (e.g., in Jupyter notebooks or certain distributed training frameworks), `swanlab.finish()` must be explicitly called. Otherwise, the experiment may remain in a 'Running' state indefinitely on the UI or fail to upload all data.

fix

Always include `swanlab.finish()` at the end of your script or experiment execution block when not relying on automatic termination.

affects: All versions

gotchaThe `resume` parameter in `swanlab.init()` has distinct behaviors (`must`, `allow`, `never`, `True`/`False`). Misunderstanding these modes can lead to unintended new experiments or errors when attempting to resume a specific run.

fix

Carefully choose the `resume` mode and provide the correct `id` for the experiment to be resumed. For example, `resume='allow'` will create a new run if the `id` is not found, while `resume='must'` will raise an error.

affects: All versions with resume functionality

gotchaBy default, `swanlab.init()` operates in 'cloud' mode, attempting to synchronize data to swanlab.cn. Users expecting purely local or offline operation must explicitly set the `mode` parameter.

fix

To run locally without cloud synchronization, initialize SwanLab with `swanlab.init(mode='local')` or `swanlab.init(mode='offline')`. For debugging, `mode='disabled'` can prevent logging entirely.

affects: All versions

deprecatedThe `swanlab.OpenApi` module has been superseded by `swanlab.Api`, which provides a more powerful and object-oriented interface for programmatic interaction.

fix

Migrate your API interactions to use the `swanlab.Api` module for improved functionality and future compatibility.

affects: Versions prior to v0.7.11 (when swanlab.Api was introduced/enhanced)

Errors

Common errors & fixes

Experiment is still shown as running on the SwanLab UI / Experiment status is Crashed

The `swanlab.finish()` function was not explicitly called, or no logs (including system metrics) were uploaded for more than 30 minutes, leading SwanLab to assume the experiment crashed.

fix

Ensure `swanlab.finish()` is called at the end of your experiment script. For network issues, check your connection. For long-running idle periods without logs, consider setting a `mode` other than `cloud` or ensuring periodic logging.

Cannot input API Key during login / Login fails with invalid API Key

There might be an issue with how the API key is being provided to the CLI, or it's being used in a context where interactive input isn't possible.

fix

Use the command-line arguments: `swanlab login --api-key <YOUR_API_KEY>` or programmatically: `import swanlab; swanlab.login(api_key='Your API Key')`. If self-hosting, also include `--host <YOUR_HOST_ADDRESS>`.

Subsequent swanlab.init() calls will be ignored (when running multiple experiments in one script)

SwanLab expects `swanlab.finish()` to be called before initializing a new experiment in the same process. Without it, subsequent `init()` calls are ignored.

fix

Add `swanlab.finish()` between each `swanlab.init()` call to properly terminate the previous experiment before starting a new one in the same script.

ValueError: Experiment ID must be a 1-64 character string. Invalid characters provided.

The `id` parameter provided to `swanlab.init()` (often for resuming experiments) does not meet the specified format requirements.

fix

Ensure the experiment `id` is a string between 1 and 64 characters long and does not contain special characters such as `/ \ # ? % :`.

Upgrade

Version history

0.8.3latest on PyPI · released Jun 16, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/SwanHubX/SwanLab ↗

packagehttps://pypi.org/project/swanlab/ ↗

homepagehttps://swanlab.cn ↗

docshttps://docs.swanlab.cn/zh/guide_cloud/general/what-is-swanlab.html ↗