SwanLab

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.

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.

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

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:

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

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>

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 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 and media for step 100-200
swanlab sync ./swanlog/run-xxx --id <experiment ID> --start-step 100 --end-step 200
OptionApplies to
--start-step / --end-stepScalars, media (inclusive)
--start-time / --end-timeScalars, media, 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.

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.