{"id":9347,"library":"swanlab","title":"SwanLab","description":"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.","status":"active","version":"0.7.15","language":"en","source_language":"en","source_url":"https://github.com/SwanHubX/SwanLab","tags":["AI/ML","experiment tracking","visualization","hyperparameter tuning","MLOps","deep learning"],"install":[{"cmd":"pip install swanlab","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"swanlab","correct":"import swanlab"},{"symbol":"swanlab.init","correct":"swanlab.init(...)"},{"symbol":"swanlab.log","correct":"swanlab.log({...})"},{"note":"Important to call explicitly in notebooks or long-running scripts to ensure data upload and proper run termination.","symbol":"swanlab.finish","correct":"swanlab.finish()"}],"quickstart":{"code":"import swanlab\nimport random\n\n# Initialize a SwanLab experiment\nrun = swanlab.init(\n    project=\"my-ml-project\",\n    experiment_name=\"basic_training_run\",\n    config={\n        \"learning_rate\": 0.01,\n        \"epochs\": 5,\n        \"batch_size\": 32\n    }\n)\n\n# Simulate a training loop\nfor epoch in range(run.config.epochs):\n    loss = 1.0 / (epoch + 1) + random.uniform(-0.1, 0.1)\n    accuracy = 0.5 + (epoch / run.config.epochs) * 0.4 + random.uniform(-0.05, 0.05)\n    \n    # Log metrics\n    swanlab.log({\"loss\": loss, \"accuracy\": accuracy})\n    print(f\"Epoch {epoch+1}, Loss: {loss:.4f}, Accuracy: {accuracy:.4f}\")\n\n# Finish the experiment explicitly (optional in most scripts, but good practice)\nswanlab.finish()","lang":"python","description":"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()`."},"warnings":[{"fix":"Always include `swanlab.finish()` at the end of your script or experiment execution block when not relying on automatic termination.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions with resume functionality"},{"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.","message":"By 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate your API interactions to use the `swanlab.Api` module for improved functionality and future compatibility.","message":"The `swanlab.OpenApi` module has been superseded by `swanlab.Api`, which provides a more powerful and object-oriented interface for programmatic interaction.","severity":"deprecated","affected_versions":"Versions prior to v0.7.11 (when swanlab.Api was introduced/enhanced)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Experiment is still shown as running on the SwanLab UI / Experiment status is Crashed"},{"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>`.","cause":"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.","error":"Cannot input API Key during login / Login fails with invalid API Key"},{"fix":"Add `swanlab.finish()` between each `swanlab.init()` call to properly terminate the previous experiment before starting a new one in the same script.","cause":"SwanLab expects `swanlab.finish()` to be called before initializing a new experiment in the same process. Without it, subsequent `init()` calls are ignored.","error":"Subsequent swanlab.init() calls will be ignored (when running multiple experiments in one script)"},{"fix":"Ensure the experiment `id` is a string between 1 and 64 characters long and does not contain special characters such as `/ \\ # ? % :`.","cause":"The `id` parameter provided to `swanlab.init()` (often for resuming experiments) does not meet the specified format requirements.","error":"ValueError: Experiment ID must be a 1-64 character string. Invalid characters provided."}]}