---
url: /en/guide_cloud/experiment_track/sync-logfile.md
---
# Upload Offline Experiment Data

> Synchronize local experiment data to SwanLab cloud/private deployment

**Use Cases:**

1. **Network interruption during training:** The server lost connection for 1 hour during model training, causing SwanLab cloud records to break.
2. **Training environment without internet:** You unfortunately discover that your company/school's training server has no internet access and doesn't allow Docker installation.
3. **Multi-device synchronization:** You're using private deployment but also want to sync experiment records to the cloud.
4. **Experiment replication:** The experiment is universally applicable to multiple projects you've created (e.g., baseline, benchmark experiments) and you want to replicate it across projects.
5. **Missing cloud records:** Training finished normally, but only part of it was recorded in the cloud (e.g., due to a temporary network outage or failed uploads), and you need to backfill the middle segment by time window or `step` range.

When encountering the above scenarios, the `swanlab sync` command can help. [API Documentation](../../api/cli-swanlab-sync.md).

::: warning Version Compatibility

The `swanlab sync` command is **not backward-compatible** with log files produced by older SwanLab SDK versions.

Starting from **SwanLab SDK `v0.8.0`**, the local log format underwent significant changes. Log files generated by `v0.8.0` and above **cannot be synced by older `swanlab sync` versions**, and conversely, old swanlog files **cannot be synced by newer SDK versions**.

**Before syncing, please verify that:**

1. The **`swanlab sync` CLI version** matches (or is older than) the **SDK version that produced the log files**.
2. If your log files were generated by an SDK older than `v0.8.0`, use that same version to run `swanlab sync`; do not upgrade.
3. If you encounter parse errors or missing data during sync, the log format is likely incompatible — install the original SDK version that generated the logs and retry.

:::

## Local Experiment Data Directory

SwanLab saves **experiment log files** by default in the `swanlog` directory of your project. You can also customize the save path using the `logdir` parameter. [Documentation](../../api/py-init.md#setting-the-log-file-save-location).

Each time you create an experiment, SwanLab automatically creates a `run-[experiment ID]` directory under `swanlog` and continuously records data to this directory.

![](https://swanlab-docs-1301372061.cos.ap-beijing.myqcloud.com/assets/en/guide_cloud/experiment_track/sync-logfile/run_dir.png)

::: warning Tips
This `run-` prefixed directory is crucial—it's the foundation for `swanlab sync`.
:::

## Upload Experiment Data

Locate the data directory you want to upload to the cloud, then execute the command:

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

:::info
By default, data will be synced to the `project` recorded in the log files (i.e., the project specified when running the experiment).\
To sync to a different project, use the `-p` option.
:::

If you see the following output, the upload was successful:

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

## Sync to Original Experiment

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

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

* By default, syncing to an existing experiment incrementally resumes from the latest progress recorded in the cloud. If a middle segment of data is missing, use the range options to backfill that specific range.

For how to obtain the experiment ID, see: [Resume Experiment/Checkpoint Training](./resume-experiment.md)

## Batch Upload

You can use wildcards for batch uploads:

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

## Upload to a Specific Project/Team Workspace

```bash
swanlab sync ./swanlog/run-xxx -p <project_name> -w <workspace_name>
```

:::warning Experiment Replication Scenario
If you want an experiment to appear in multiple projects, use the above command to upload it to multiple projects.
:::

## Upload to Private Deployment

```bash
swanlab sync ./swanlog/run-xxx --host <private_deployment_address>
```

## Range Sync

A default full sync only appends data after the latest progress recorded in the cloud. If only a middle segment of training data is missing (for example, due to a temporary database outage while subsequent uploads recovered), you can use the range options to backfill records within that specific interval:

```bash
# By time: 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"

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

| Option                        | Applies to                                            |
| ----------------------------- | ----------------------------------------------------- |
| `--start-step` / `--end-step` | Scalars, media, histograms (inclusive)                |
| `--start-time` / `--end-time` | Scalars, media, histograms, terminal logs (inclusive) |

When both `step` and time ranges are specified, their intersection is used. Specifying only a `step` range does not sync terminal logs; use a time range if you need to backfill terminal logs.

::: warning Avoid re-syncing existing ranges
Range sync directly uploads all records within the specified window without automatically skipping data that already exists in the cloud. If the sync window overlaps with existing cloud records:

* **Scalars**: Charts align by `step` and are not duplicated, but experiment summary statistics may be affected;
* **Media** (images, audio, etc.): Duplicate media uploads at the same `step` are displayed as multiple entries.

Keep the range as narrow as the actual gap. If you only need to append data at the end of an experiment, run a **default full sync (without range options)**, which never produces duplicates.

:::

> 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.
