{"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":"python","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,"search_vec":"'0.7.15':51 '30':42 'ai':13,44 'ai/ml':58 'automat':21 'cloud':35 'collabor':31 'comparison':26 'current':48 'deep':65 'experi':18,25,59 'framework':46 'frequent':53 'hyperparamet':23,62 'integr':39 'learn':66 'librari':6 'log':22 'mainstream':43 'manag':11 'minor':56 'mlop':64 'multi':29 'multi-us':28 'offer':17 'offlin':37 'patch':54 'process':15 'python':5 'record':24 'releas':57 'streamlin':8 'support':33 'swanlab':1,2,32 'track':9,19,60 'train':14,45 'tune':63 'usag':38 'user':30 'version':49 'visual':20,61","created_at":"2026-04-16T18:49:44.390530+00:00","updated_at":"2026-04-16T18:49:44.390530+00:00","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."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.8.3","cli_name":"swanlab","cli_version":"SwanLab 0.7.18","type":"library","homepage":"https://swanlab.cn","github":"https://github.com/SwanHubX/SwanLab","docs":"https://docs.swanlab.cn/zh/guide_cloud/general/what-is-swanlab.html","changelog":null,"pypi":"https://pypi.org/project/swanlab/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","observability","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}