---
url: /en/api/cli-swanlab-sync.md
---
# swanlab sync

```bash
swanlab sync [options] [logdir]
```

| Option              | Description                                                                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-k`, `--api-key`   | API key for authentication. If not specified, the default API key from the environment will be used. If specified, this API key will be used for login but won't be saved.   |
| `-h`, `--host`      | The host address for syncing logs. If not specified, the default host (`https://swanlab.cn`) will be used.                                                                   |
| `-w`, `--workspace` | The workspace for syncing logs. If not specified, the default workspace will be used.                                                                                        |
| `-p`, `--project`   | The project for syncing logs. If not specified, the default project will be used.                                                                                            |
| `-i`, `--id`        | The experiment ID to sync the logs to. It can only be used when the path is a single directory.                                                                              |
| `--start-step`      | Only sync scalar/media/histogram records whose `step` is greater than or equal to this value (inclusive).                                                                    |
| `--end-step`        | Only sync scalar/media/histogram records whose `step` is less than or equal to this value (inclusive).                                                                       |
| `--start-time`      | Only sync records at or after this time. Accepts ISO 8601 (e.g. `2026-10-20 10:00:00`) or a Unix timestamp in seconds/milliseconds; parsed in the local timezone by default. |
| `--end-time`        | Only sync records at or before this time. Same formats as `--start-time`.                                                                                                    |

## Introduction

Sync local logs to SwanLab cloud or private deployment.

## Version Comparison

> The version comparison only applies to the `swanlab sync` command. For the Python library version comparison, please refer to [Python Library Version Comparison](./cli-swanlab-sync.md#python-library-version-comparison).

| swanlab library version | Feature                                                                         | Supported log files                                    |
| ----------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------ |
| >=0.6.8                 | Support syncing logs from abnormal terminal of training; support `id` parameter | Logs generated by `>=0.6.8` version of swanlab library |
| <0.6.8                  | -                                                                               | Logs generated by `<0.6.8` version of swanlab library  |

## Command Line Examples

Locate the log directory you want to upload to the cloud (by default, it's the `run-` prefixed directory under `swanlog`), then execute the command:

```bash
swanlab sync ./swanlog/run-xxx
```

::: info
By default, logs will be synced to the `project` recorded in the log files, which is the `project` set when running the experiment.\
If you want to sync to a different project, you can use the `-p` option to specify the project.
:::

If you see the following output, it indicates a successful sync:

![swanlab sync](https://swanlab-docs-1301372061.cos.ap-beijing.myqcloud.com/assets/en/api/cli-swanlab-sync/console.png)

## Batch Upload

```bash
swanlab sync ./swanlog/run-*
```

## Sync to the Original Experiment

If you don't want to create a new experiment but sync to the original one, use the `--id` parameter:

```bash
swanlab sync ./swanlog/run-xxx --id <experiment ID>
```

* During synchronization, the target experiment status briefly shows as `RUNNING` and automatically restores to its original finished state once completed.
* If the experiment is still actively training, it remains `RUNNING` after the sync without interrupting or affecting the ongoing training.
* By default, syncing incrementally resumes from the latest progress in the cloud. To backfill a missing middle segment, use the range options described in [Range Sync](#range-sync).

Experiment ID can be obtained from [Resume Experiment/Resume Training](../guide_cloud/experiment_track/resume-experiment.md).

## Range Sync

By default, `swanlab sync --id` **incrementally resumes** from the latest progress recorded in the cloud. If a **middle segment** of data is missing (for example, due to a temporary network interruption during training while subsequent data was uploaded normally), the default incremental sync will not backfill that gap automatically.

In this case, you can use the range options to backfill records within a specific window:

| Option                        | Applies to                                | Description                                                                 |
| ----------------------------- | ----------------------------------------- | --------------------------------------------------------------------------- |
| `--start-step` / `--end-step` | Scalars, media, histograms                | Sync only records whose `step` falls within the specified range (inclusive) |
| `--start-time` / `--end-time` | Scalars, media, histograms, terminal logs | Filter by the timestamp when the record was generated (inclusive)           |

* When both `step` and time ranges are specified, their intersection is used.
* When only a `step` range is specified, **terminal logs are not synced** (terminal logs can only be filtered by time). Use a time range if you need to backfill terminal logs.
* While training is still in progress, you can also run a range sync with `--id` against the same experiment from another terminal without interrupting or affecting the ongoing training.
* Time options accept standard date-time formats (e.g. `2026-10-20 10:00:00`) as well as Unix timestamps in seconds or milliseconds. Values without a timezone offset are parsed using the local timezone of the machine running the command by default.

```bash
# Backfill scalars, media and histograms for step 100-200 only
swanlab sync ./swanlog/run-xxx --id <experiment ID> --start-step 100 --end-step 200

# Backfill scalars, media, histograms and terminal logs between 10:00 and 12:00
swanlab sync ./swanlog/run-xxx --id <experiment ID> \
    --start-time "2026-10-20 10:00:00" --end-time "2026-10-20 12:00:00"

# Intersection of step and time ranges
swanlab sync ./swanlog/run-xxx --id <experiment ID> \
    --start-step 100 --end-step 200 --start-time "2026-10-20 10:00:00"
```

::: warning
⚠️ Note: Avoid re-syncing ranges that already exist in the cloud. Range sync directly uploads all records within the specified window and does not automatically skip existing cloud data.
:::

Therefore:

* To append data missing at the end of an experiment, run a default **full sync** (without range options), which never produces duplicates.
* When using **range sync** to backfill a missing middle segment, keep the range as narrow as the actual gap.

## Python Code Example

```python
import swanlab

swanlab.login(api_key="Your API Key")

# Full sync: uses the project recorded in the log files
swanlab.sync("./swanlog/run-xxx")

# Specify project/workspace
swanlab.sync(
    "./swanlog/run-xxx",
    settings=swanlab.Settings(
        project=swanlab.Settings.Project(workspace="swanlab", name="sync_test")
    ),
)

# Range sync: backfill step 100-200 into an existing experiment
swanlab.sync(
    "./swanlog/run-xxx",
    settings=swanlab.Settings(run=swanlab.Settings.Run(id="<experiment ID>")),
    start_step=100,
    end_step=200,
)
```