conda create -n SoccerNet python pip conda activate SoccerNet pip install SoccerNet # pip install -e https://github.com/SoccerNet/SoccerNet # pip install -e .
SoccerNet data has moved off the legacy KAUST ownCloud drive (EXRCS) onto the
SoccerNet organization on Hugging Face.
downloadDataTask, downloadGame, and downloadGames all fetch from Hugging
Face by default (source="HuggingFace"); pass source="EXRCSDrive" to fall
back to the legacy drive for anything not yet migrated. Call signatures and
local folder layout are unchanged either way, and password= is accepted but
ignored (with a warning) wherever access is now controlled by your Hugging
Face account instead. For gated repositories, follow the access steps below.
For datasets marked NDA-gated, access requires an electronic NDA signature and manual approval:
- Sign in to your Hugging Face account.
- Open the dataset repository you want to access.
- Complete the requested information, read the linked SoccerNet Non-Disclosure Agreement, and electronically sign it using the acknowledgment checkbox.
- Submit your request and wait for manual approval by the SoccerNet team.
- Download the dataset using the same account after approval.
Access is granted separately for each repository. Approval for
SoccerNet_raw_HQ does not automatically grant access to SN-BAS-2024,
SN-BAS-2025, or SN-PCBAS-2026. Existing approvals for these repositories
remain valid.
Install the Hugging Face command-line tool and sign in with the account that received access:
pip install --upgrade huggingface_hub hf auth login
If prompted for an access token, use one from the approved account with read
access to the dataset. For example, download SN-BAS-2025 with:
hf download SoccerNet/SN-BAS-2025 --repo-type dataset --local-dir SoccerNet/SN-BAS-2025
Replace the repository ID and local directory with the dataset you want to download. Request access on that repository's page before downloading it.
| Dataset | Hugging Face repo | Access |
|---|---|---|
| Camera Calibration 2023 | SN-Calibration-2023 |
public |
| Camera Calibration (legacy, pre-2023) | SN-Calibration |
public |
| Re-Identification 2023 | SN-ReID-2023 |
public |
| Re-Identification (legacy) | same data as SN-ReID-2023 |
public |
| Player Tracking 2023 | SN-Tracking-2023 |
public |
| Player Tracking (legacy) | same data as SN-Tracking-2023 |
public |
| Jersey Number Recognition 2023 | SN-Jersey-2023 |
public |
| Ball Action Spotting 2023 | SN-BAS-2023 |
gated |
| Ball Action Spotting 2024 | SN-BAS-2024 |
NDA-gated; password-free ZIPs |
| Ball Action Spotting 2025 | SN-BAS-2025 |
NDA-gated; password-free ZIPs |
| Player-Centric Ball Action Spotting 2026 | SN-PCBAS-2026 |
NDA-gated; password-free ZIPs |
| Action Spotting (all editions) | per-game features/labels — see below | public |
| Dense Video Captioning 2023 / 2024 | per-game features/labels — see below | public |
| Foul Recognition (MVFouls) 2024 | SN-MVFouls-2024 |
public |
| Foul Recognition (MVFouls) 2025 | SN-MVFouls-2025 |
public |
| Game State Reconstruction 2024 | SN-GSR-2024 |
public |
| Game State Reconstruction 2025 | SN-GSR-2025 |
public |
| Monocular Depth Estimation (football / basketball) | SN-Depth (branches football, basketball) |
public |
| Monocular Depth Estimation 2025 | SN-Depth-2025 |
public |
| Pre-extracted per-game features (all editions) | SN-Features — one branch per feature type: baidu-soccer-embeddings, resnet-tf2, resnet-tf2-pca512, player-boundingbox-maskrcnn, field-calib-ccbv |
public |
| Per-game labels (all editions) | SN-Labels — Labels.json, Labels-v2.json, Labels-v3.json, Labels-cameras.json, Labels-caption.json |
public |
| Raw broadcast videos, train/valid/test (224p/720p/HQ + frames/clips) | SoccerNet_raw_HQ (branches videos-224p, videos-720p, videos-HQ, frames-720p-2fps, clips-720p-10s, frames-v3) |
gated |
| Raw broadcast videos, challenge split (224p/720p/HQ/LQ) | SoccerNet_raw_HQ_Challenge (branches videos-224p, videos-720p, videos-HQ, videos-LQ) |
gated |
| Held-out test/challenge ground truth (all tasks above) | SN-GroundTruth, one folder per task |
private |
| SpiideoSynLoc (4K/FullHD synchronized multi-camera images) | hosted on Spiideo's own S3, not part of this migration | see downloadDataTask(task="SpiideoSynLoc") |
For SoccerNet in OSL Action Spotting format, use OpenSportsLab/OSL-SoccerNet directly (sharded WebDataset format — datasets.load_dataset unpacks the .tar shards for you):
from datasets import load_dataset dataset = load_dataset("OpenSportsLab/OSL-SoccerNet", revision="ResNET_PCA512") # or "224p", "720p"
- SoccerNet main folder
- Leagues (england_epl/europe_uefa-champions-league/france_ligue-1/...)
- Seasons (2014-2015/2015-2016/2016-2017)
- Games (format: "{Date} - {Time} - {HomeTeam} {Score} {AwayTeam}")
-
SoccerNet-v2 - Labels / Manual Annotations
- video.ini: information on start/duration for each half of the game in the HQ video, in second
- Labels-v2.json: Labels from SoccerNet-v2 - action spotting
- Labels-cameras.json: Labels from SoccerNet-v1 - camera shot segmentation
-
SoccerNet-v2 - Videos / Automatically Extracted Features
- 1_224p.mkv: 224p video 1st half - timmed with start/duration from HQ video - resolution 224*398 - 25 fps
- 2_224p.mkv: 224p video 2nd half - timmed with start/duration from HQ video - resolution 224*398 - 25 fps
- 1_720p.mkv: 720p video 1st half - timmed with start/duration from HQ video - resolution 720*1280 - 25 fps
- 2_720p.mkv: 720p video 2nd half - timmed with start/duration from HQ video - resolution 720*1280 - 25 fps
- 1_ResNET_TF2.npy: ResNET features @2fps for 1st half from SoccerNet-v2, extracted using TF2
- 2_ResNET_TF2.npy: ResNET features @2fps for 2nd half from SoccerNet-v2, extracted using TF2
- 1_ResNET_TF2_PCA512.npy: ResNET features @2fps for 1st half from SoccerNet-v2, extracted using TF2, with dimensionality reduced to 512 using PCA
- 2_ResNET_TF2_PCA512.npy: ResNET features @2fps for 2nd half from SoccerNet-v2, extracted using TF2, with dimensionality reduced to 512 using PCA
- 1_ResNET_5fps_TF2.npy: ResNET features @5fps for 1st half from SoccerNet-v2, extracted using TF2
- 2_ResNET_5fps_TF2.npy: ResNET features @5fps for 2nd half from SoccerNet-v2, extracted using TF2
- 1_ResNET_5fps_TF2_PCA512.npy: ResNET features @5fps for 1st half from SoccerNet-v2, extracted using TF2, with dimensionality reduced to 512 using PCA
- 2_ResNET_5fps_TF2_PCA512.npy: ResNET features @5fps for 2nd half from SoccerNet-v2, extracted using TF2, with dimensionality reduced to 512 using PCA
- 1_ResNET_25fps_TF2.npy: ResNET features @25fps for 1st half from SoccerNet-v2, extracted using TF2
- 2_ResNET_25fps_TF2.npy: ResNET features @25fps for 2nd half from SoccerNet-v2, extracted using TF2
- 1_player_boundingbox_maskrcnn.json: Player Bounding Boxes @2fps for 1st half, extracted with MaskRCNN
- 2_player_boundingbox_maskrcnn.json: Player Bounding Boxes @2fps for 2nd half, extracted with MaskRCNN
- 1_field_calib_ccbv.json: Field Camera Calibration @2fps for 1st half, extracted with CCBV
- 2_field_calib_ccbv.json: Field Camera Calibration @2fps for 2nd half, extracted with CCBV
- 1_baidu_soccer_embeddings.npy: Frame Embeddings for 1st half from https://github.com/baidu-research/vidpress-sports
- 2_baidu_soccer_embeddings.npy: Frame Embeddings for 2nd half from https://github.com/baidu-research/vidpress-sports
-
Legacy from SoccerNet-v1
- Labels.json: Labels from SoccerNet-v1 - action spotting for goals/cards/subs only
- 1_C3D.npy: C3D features @2fps for 1st half from SoccerNet-v1
- 2_C3D.npy: C3D features @2fps for 2nd half from SoccerNet-v1
- 1_C3D_PCA512.npy: C3D features @2fps for 1st half from SoccerNet-v1, with dimensionality reduced to 512 using PCA
- 2_C3D_PCA512.npy: C3D features @2fps for 2nd half from SoccerNet-v1, with dimensionality reduced to 512 using PCA
- 1_I3D.npy: I3D features @2fps for 1st half from SoccerNet-v1
- 2_I3D.npy: I3D features @2fps for 2nd half from SoccerNet-v1
- 1_I3D_PCA512.npy: I3D features @2fps for 1st half from SoccerNet-v1, with dimensionality reduced to 512 using PCA
- 2_I3D_PCA512.npy: I3D features @2fps for 2nd half from SoccerNet-v1, with dimensionality reduced to 512 using PCA
- 1_ResNET.npy: ResNET features @2fps for 1st half from SoccerNet-v1
- 2_ResNET.npy: ResNET features @2fps for 2nd half from SoccerNet-v1
- 1_ResNET_PCA512.npy: ResNET features @2fps for 1st half from SoccerNet-v1, with dimensionality reduced to 512 using PCA
- 2_ResNET_PCA512.npy: ResNET features @2fps for 2nd half from SoccerNet-v1, with dimensionality reduced to 512 using PCA
-
- Games (format: "{Date} - {Time} - {HomeTeam} {Score} {AwayTeam}")
- Seasons (2014-2015/2015-2016/2016-2017)
- Leagues (england_epl/europe_uefa-champions-league/france_ligue-1/...)
from SoccerNet.Downloader import SoccerNetDownloader mySoccerNetDownloader = SoccerNetDownloader(LocalDirectory="path/to/soccernet") # Download SoccerNet labels (fetched from SoccerNet/SN-Labels by default) mySoccerNetDownloader.downloadGames(files=["Labels.json"], split=["train", "valid", "test"]) # download labels mySoccerNetDownloader.downloadGames(files=["Labels-v2.json"], split=["train", "valid", "test"]) # download labels SN v2 mySoccerNetDownloader.downloadGames(files=["Labels-cameras.json"], split=["train", "valid", "test"]) # download labels for camera shot # Download SoccerNet features (fetched from SoccerNet/SN-Features by default, one branch per feature type) mySoccerNetDownloader.downloadGames(files=["1_ResNET_TF2.npy", "2_ResNET_TF2.npy"], split=["train", "valid", "test"]) # download Features mySoccerNetDownloader.downloadGames(files=["1_ResNET_TF2_PCA512.npy", "2_ResNET_TF2_PCA512.npy"], split=["train", "valid", "test"]) # download Features reduced with PCA mySoccerNetDownloader.downloadGames(files=["1_player_boundingbox_maskrcnn.json", "2_player_boundingbox_maskrcnn.json"], split=["train", "valid", "test"]) # download Player Bounding Boxes inferred with MaskRCNN mySoccerNetDownloader.downloadGames(files=["1_field_calib_ccbv.json", "2_field_calib_ccbv.json"], split=["train", "valid", "test"]) # download Field Calibration inferred with CCBV mySoccerNetDownloader.downloadGames(files=["1_baidu_soccer_embeddings.npy", "2_baidu_soccer_embeddings.npy"], split=["train", "valid", "test"]) # download Frame Embeddings from https://github.com/baidu-research/vidpress-sports # You can also fetch any of the above directly with huggingface_hub, e.g.: # from huggingface_hub import snapshot_download # snapshot_download(repo_id="SoccerNet/SN-Features", repo_type="dataset", revision="resnet-tf2-pca512", local_dir="path/to/soccernet") # Download SoccerNet Challenge set features (fetched from Hugging Face, no password needed) mySoccerNetDownloader.downloadGames(files=["1_ResNET_TF2.npy", "2_ResNET_TF2.npy"], split=["challenge"]) # download ResNET Features mySoccerNetDownloader.downloadGames(files=["1_ResNET_TF2_PCA512.npy", "2_ResNET_TF2_PCA512.npy"], split=["challenge"]) # download ResNET Features reduced with PCA mySoccerNetDownloader.downloadGames(files=["1_224p.mkv", "2_224p.mkv"], split=["challenge"]) # download 224p Videos - gated, request access at https://huggingface.co/datasets/SoccerNet/SoccerNet_raw_HQ_Challenge mySoccerNetDownloader.downloadGames(files=["1_720p.mkv", "2_720p.mkv"], split=["challenge"]) # download 720p Videos - gated, same repo as above mySoccerNetDownloader.downloadGames(files=["1_player_boundingbox_maskrcnn.json", "2_player_boundingbox_maskrcnn.json"], split=["challenge"]) # download Player Bounding Boxes inferred with MaskRCNN mySoccerNetDownloader.downloadGames(files=["1_field_calib_ccbv.json", "2_field_calib_ccbv.json"], split=["challenge"]) # download Field Calibration inferred with CCBV mySoccerNetDownloader.downloadGames(files=["1_baidu_soccer_embeddings.npy", "2_baidu_soccer_embeddings.npy"], split=["challenge"]) # download Frame Embeddings from https://github.com/baidu-research/vidpress-sports # Download development kit per task mySoccerNetDownloader.downloadDataTask(task="calibration-2023", split=["train", "valid", "test", "challenge"]) mySoccerNetDownloader.downloadDataTask(task="caption-2023", split=["train", "valid", "test", "challenge"]) mySoccerNetDownloader.downloadDataTask(task="jersey-2023", split=["train", "test", "challenge"]) mySoccerNetDownloader.downloadDataTask(task="reid-2023", split=["train", "valid", "test", "challenge"]) mySoccerNetDownloader.downloadDataTask(task="spotting-2023", split=["train", "valid", "test", "challenge"]) mySoccerNetDownloader.downloadDataTask(task="spotting-ball-2023", split=["train", "valid", "test", "challenge"]) # gated on Hugging Face - request access at https://huggingface.co/datasets/SoccerNet/SN-BAS-2023, then `hf auth login` mySoccerNetDownloader.downloadDataTask(task="tracking-2023", split=["train", "test", "challenge"]) mySoccerNetDownloader.downloadDataTask(task="SpiideoSynLoc", split=["train","valid","test","challenge"]) # 4K Images mySoccerNetDownloader.downloadDataTask(task="SpiideoSynLoc", split=["train","valid","test","challenge"], version="fullhd") # FullHD Images # Download SoccerNet videos - fetched from SoccerNet/SoccerNet_raw_HQ (train/valid/test) # or SoccerNet/SoccerNet_raw_HQ_Challenge (challenge) by default; both gated, # request access on the dataset page then `hf auth login` (no password needed) mySoccerNetDownloader.downloadGames(files=["1_224p.mkv", "2_224p.mkv"], split=["train", "valid", "test"]) # download 224p Videos mySoccerNetDownloader.downloadGames(files=["1_720p.mkv", "2_720p.mkv"], split=["train", "valid", "test"]) # download 720p Videos mySoccerNetDownloader.downloadRAWVideo(dataset="SoccerNet") # download 720p Videos mySoccerNetDownloader.downloadRAWVideo(dataset="SoccerNet-Tracking") # download single camera RAW Videos - still EXRCS-only, not yet migrated mySoccerNetDownloader.downloadGame(files=["1_720p.mkv", "2_720p.mkv"], game="europe_uefa-champions-league/2016-2017/2017-04-18 - 21-45 Real Madrid 4 - 2 Bayern Munich") # download video for a single game # Fall back to the legacy EXRCS drive for anything not yet migrated (pass source="EXRCSDrive") mySoccerNetDownloader.password = "Password for videos? (contact the author)" mySoccerNetDownloader.downloadGames(files=["1_720p.mkv", "2_720p.mkv"], split=["train", "valid", "test"], source="EXRCSDrive")
For SoccerNet in OSL Action Spotting format, use OpenSportsLab/OSL-SoccerNet directly:
from huggingface_hub import snapshot_download snapshot_download(repo_id="OpenSportsLab/OSL-SoccerNet", repo_type="dataset", revision="ResNET_PCA512", local_dir="path/to/soccernet")
from SoccerNet.utils import getListGames print(getListGames(split="train")) # return list of games recommended for training print(getListGames(split="valid")) # return list of games recommended for validation print(getListGames(split="test")) # return list of games recommended for testing print(getListGames(split="challenge")) # return list of games recommended for challenge print(getListGames(split=["train", "valid", "test", "challenge"])) # return list of games for training, validation and testing print(getListGames(split="v1")) # return list of games from SoccerNetv1 (train/valid/test)