Sharing Experiments

To share experiments, you can:

Send live experiments to Studio to view metrics and plots.
Push completed experiments with dvc exp push, and optionally manage them in Studio.

Live metrics and plots

You can send live experiments to Studio, which will show updates showing intermediate results for metrics and plots in any running experiments. To start sharing live metrics to Studio, get your Studio token and save it in your dvc config or DVC_STUDIO_TOKEN environment variable. For example, to set it globally for all of a user's projects:

$ dvc config --global studio.token ***

While the experiment runs, you will see live updates like this in Studio:

Live metrics in Studio

Live plots in Studio

See DVC config for how to enable/disable live metrics and how to configure a different Studio URL or Git repository, or see the Studio guide on live experiments for more information on how to setup, view, and compare.

Push experiments

You can upload a completed experiment using dvc exp push. For example, push experiment quare-zips to Git remote origin:

$ dvc exp push origin quare-zips

If you don't know your Git remote, check with git remote -v or see troubleshooting for problems.

By default, DVC will also share cached data that is tracked by DVC, which requires remote storage (e.g. Amazon S3 or SSH). Add the --no-cache flag to exclude sharing cached data.

You can optionally manage your pushed experiments from Studio. If you have saved your token as described above for live experiments, DVC will notify Studio when you push an experiment. Otherwise, you may use the reload button in Studio.

⚙️ How pushing and pulling experiments works

dvc exp push pushes experiment commits that Git can upload to remote servers like GitHub but don't show up in the UI (so they don't clutter your repo) and can be cleaned up without affecting the rest of your project.

To understand how dvc exp push works, let's compare to pushing a persistent commit. With a typical Git commit, you would use git push to upload it to your Git remote and dvc push to upload the corresponding data to your DVC remote.

 ┌────────────────┐  ┌────────────────┐
 ├────────────────┤  │   DVC remote   │ Remote locations
 │   Git remote   │  │    storage     │
 │                │  ├────────────────┤
 └────────────────┘  └────────────────┘
         ▲                    ▲
         │                    │
      git push             dvc push
      git pull             dvc pull
         │                    │
         ▼                    ▼
 ┌────────────────┐  ┌────────────────┐
 │    Code and    │  │      Data      │
 │    metafiles   │  │    (cached)    │ Local project
 └────────────────┘  └────────────────┘

dvc exp push and dvc exp pull take care of synchronizing to/from both Git and DVC remotes as needed:

 ┌────────────────┐  ┌────────────────┐
 ├────────────────┤  │   DVC remote   │ Remote locations
 │   Git remote   │  │    storage     │
 │                │  ├────────────────┤
 └────────────────┘  └────────────────┘
         ▲                    ▲
         │   dvc exp push     │
         │   dvc exp pull     │
         ▼                    ▼
 ┌─────────────────┐ ┌────────────────┐
 │    Code and     │ │      Data      │
 │    metafiles    │ │    (cached)    │ Local project
 └─────────────────┘ └────────────────┘

Pull experiments

To download an experiment, use dvc exp pull (with the Git remote and experiment name).

$ dvc exp pull origin quare-zips

This puts all the necessary files and data (from both Git and DVC remotes) in your project. Add the --no-cache flag to exclude pulling from the DVC remote.

You can find experiments to pull in Studio or list remote experiments from the command line.

DVC experiments are not fetched when cloning a DVC repository (to avoid cluttering your local repo). You must dvc exp pull the ones you want.

Use the --rev/--num/--all-commits options of dvc exp push and dvc exp pull to share many experiments at once. E.g., to upload all experiments based on the latest commit, target the Git HEAD:

$ dvc exp push --rev HEAD origin

Push a persistent experiment

To share an individual experiment the same way you share other Git commits, turn it into a persistent Git commit (we use dvc exp branch below) and share it like any project version.

$ dvc exp branch quare-zips
Git branch 'quare-zips-branch' has been created from experiment 'quare-zips'.

$ git checkout quare-zips-branch
Switched to branch 'quare-zips-branch'

$ git push origin quare-zips-branch

If you only need to share code and metadata (like parameters and metrics), then pushing to Git should be enough.

You may also have cached data, models, etc. tracked by DVC. To share these, dvc push them to remote storage (e.g. Google Drive or NAS).

$ dvc push