--- url: /en/api/py-init.md --- # swanlab.init ```python init( project: str = None, workspace: str = None, experiment_name: str = None, description: str = None, job_type: str = None, group: str = None, tags: List[str] = None, config: Union[dict, str] = None, logdir: str = None, mode: MODES = None, on_online_error: Literal['disabled', 'offline', 'raise'] = None, load: str = None, public: bool = None, callbacks: List[SwanKitCallback] = None, settings: Settings = None, color: str = None, id: str = None, resume: Union[Literal['must', 'allow', 'never'], bool] = None, reinit: bool = None, parallel: str = None, **kwargs, ) ``` | Parameter | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | project | (str) The name of the project. If not specified, the name of the current working directory will be used. | | workspace | (str) The workspace. By default, experiments are synchronized to your personal space. If you want to upload to an organization, specify the organization's username. | | experiment_name | (str) The name of the experiment. If not specified, it will default to a format like "swan-1" (animal name + sequence number). | | job_type | (str) The type of job. If not specified, it will default to empty string. | | group | (str) The group of the experiment. If not specified, it will default to None. | | tags | (list) Tags for the experiment. Can pass a list of strings, and the tags will be displayed in the tag bar at the top of the experiment. | | description | (str) A description of the experiment. If not specified, it defaults to None. | | config | (dict, str) Configuration for the experiment. You can record hyperparameters and other information here. Supports passing a configuration file path (yaml or json). | | logdir | (str) The path to store offline dashboard log files. Defaults to `swanlog`. When `core.skip_store=True` is enabled, this directory is not created locally. | | mode | (str) Sets the mode for creating SwanLab experiments. Options are "online", "local", "offline", or "disabled". Default is "online".`online`: Uploads the experiment to the SwanLab cloud (public or private deployment).`offline`: Only records experiment data locally.`local`: Does not upload to the cloud but records experiment information locally.`disabled`: Neither uploads nor records. | | on_online_error | (str) Only effective in `online` mode. Fallback strategy when cloud service is unavailable. Options: `"offline"`, `"disabled"`, `"raise"`. Defaults to None (i.e., `"offline"`).`"offline"`: Fallback to offline mode, continuing to log locally, which can be synced to the cloud via `swanlab sync` later.`"disabled"`: Fallback to disabled mode; training continues without logging any data.`"raise"`: Do not fallback; raise an error directly.Fallback is triggered only by transient errors such as network timeouts or service unavailability; authentication and configuration errors always raise an error. | | load | (str) The path to a configuration file to load. Supports yaml and json files. | | public | (bool) Sets the visibility of the SwanLab project created directly via code. Default is False (private). | | callbacks | (list) Sets experiment callback functions. Supports subclasses of `swanlab.toolkit.callback.SwanKitCallback`. | | name | (str) Same effect as `experiment_name`. Lower priority than `experiment_name`. | | notes | (str) Same effect as `description`. Lower priority than `description`. | | settings | (dict) Settings for the experiment. Supports passing a `swanlab.Settings` object. | | id | (str) The ID of the last experiment. Used to resume the last experiment. Supports 1–64 custom characters; characters `/ \ # ? % :` are not allowed. | | color | (str) The color for the experiment, used to distinguish different experiments in the dashboard. Supports three formats: preset color names (e.g., `"green"`, `"blue"`), RGB strings (e.g., `"rgb(82,141,89)"`), or hex color codes (e.g., `"#528d59"` or `"528d59"`). Defaults to None (random color). Invalid formats will trigger a warning and fall back to a random color. | | resume | (str) Resume mode. Can be "must", "allow", "never", or True/False. Default is None.`must`: You must pass the `id` parameter, and the experiment must exist.`allow`: If an experiment exists, it will be resumed. Otherwise, a new experiment will be created.`never`: The `id` parameter cannot be passed, and a new experiment will be created. (This is equivalent to not enabling `resume`.) | | reinit | (bool) Whether to reinitialize the experiment. If True, the last experiment will be `finish`ed every time `swanlab.init()` is called; default is None. | | parallel | (str) Parallel mode. Options are `"none"` or `"shared"`. Defaults to `"none"`.`"shared"`: Shared parallel mode, allowing multiple distributed processes to upload metrics to the same experiment simultaneously. Automatically forces `mode='online'` and `resume='allow'`, and auto-generates an 8-character random `id` if none is provided. | ## Introduction • In machine learning workflows, you can add `swandb.init()` at the beginning of training and testing scripts. SwanLab will track every step of the machine learning process. • `swanlab.init()` spawns a new background process to log data to the experiment. By default, it also synchronizes the data to swanlab.cn, allowing you to view real-time visualizations online. • Before using `swanlab.log()` to record data, you must call `swanlab.init()`: ```python import swanlab swanlab.init() swanlab.log({"loss": 0.1846}) ``` • Calling `swanlab.init()` returns an object of type `SwanLabRun`, which can also perform `log` operations: ```python import swanlab run = swanlab.init() run.log({"loss": 0.1846}) ``` • At the end of the script, `swanlab.finish` will be automatically called to conclude the SwanLab experiment. However, if `swanlab.init()` is called from a subprocess (e.g., in a Jupyter notebook), you must explicitly call `swanlab.finish` at the end of the subprocess. ```python import swanlab swanlab.init() swanlab.finish() ``` ## Additional Usage ### Setting Project, Experiment Name, and Description ```python swanlab.init( project="cats-detection", experiment_name="YoloX-baseline", description="Baseline experiment for the YoloX detection model, primarily for subsequent comparisons.", ) ``` ### Setting Tags ```python swanlab.init( tags=["yolo", "detection", "baseline"] ) ``` ### Setting Group ```python swanlab.init( group="good_try", ) ``` ### Setting the Log File Save Location The following code demonstrates how to save log files to a custom directory: ```python swanlab.init( logdir="path/to/my_custom_dir", ) ``` ### Setting Experiment Color ```python # Using a preset color name swanlab.init(color="green") # Using a hex color code swanlab.init(color="#528d59") # Using an RGB string swanlab.init(color="rgb(82,141,89)") ``` ### Adding Experiment Metadata to the Configuration ```python swanlab.init( config={ "learning-rate": 1e-4, "model": "CNN", } ) ``` ### Uploading to an Organization ```python swanlab.init( workspace="[organization's username]" ) ``` ### Plugins For more information about plugins, refer to the [Plugins](../plugin/plugin-index.md) documentation. ```python from swanlab.plugin.notification import EmailCallback email_callback = EmailCallback(...) swanlab.init( callbacks=[email_callback] ) ``` ### Parallel Mode `parallel="shared"` is designed for multi-process distributed training, where multiple processes upload metrics to the same experiment simultaneously: ```python # Multiple distributed processes use the same id, and metrics are aggregated under one experiment swanlab.init( parallel="shared", id="my-distributed-run", # All processes use the same id ) ``` If no `id` is provided, SwanLab auto-generates an 8-character random ID: ```python import os # Share the same id across all processes via an environment variable RUN_ID = os.environ.get("RUN_ID", swanlab.util.generate_id()) swanlab.init( parallel="shared", id=RUN_ID, ) ``` "Resume Training" refers to the ability to resume training from a previous state. If you previously had an experiment with the status of `completed` or `interrupted`, and you need to add more experimental data, you can use the `resume` and `id` parameters to restore this experiment. ```python swanlab.init( resume=True, id="14pk4qbyav4toobziszli", # supports 1-64 custom characters ) ``` The experiment ID can be found in the experiment's "Environment" tab or in the URL. It must be a 21-character string. :::tip Use Cases for `resume` 1. The previous training process was interrupted. You want to continue training based on a checkpoint and have the experiment chart continue from the previous swanlab experiment, rather than creating a new one. 2. Training and evaluation are split into two separate processes, but you want both the evaluation and training records to appear in the same swanlab experiment. 3. Some configuration parameters were incorrectly filled out, and you want to update them. ::: :::warning ⚠️ Notes 1. Experiments generated by cloning a project cannot be resumed. ::: Breakpoint continuation supports three modes: 1. `allow`: If an experiment corresponding to the provided `id` exists under the project, it will be resumed. Otherwise, a new experiment will be created. 2. `must`: If an experiment corresponding to the provided `id` exists under the project, it will be resumed. Otherwise, an error will be thrown. 3. `never`: The `id` parameter cannot be passed, and a new experiment will be created instead. (This is equivalent to not enabling `resume`.) :::info Setting `resume=True` has the same effect as `resume="allow"`.\ Setting `resume=False` has the same effect as `resume="never"`. ::: Test code: ```python import swanlab run = swanlab.init() swanlab.log({"loss": 2, "acc": 0.4}) run.finish() run = swanlab.init(resume=True, id=run.id) swanlab.log({"loss": 0.2, "acc": 0.9}) ``` ## Deprecated Parameters • `cloud`: Replaced by the `mode` parameter in v0.3.4. The parameter is still available and will override the `mode` setting.