Sports PVR for Usenet and Torrents

Like Sonarr & Radarr, but for sports events. Monitors sports leagues, searches your indexers
for releases, and handles file renaming, organization, and media server integration.

Most people should run Sportarr with Docker (above). To run it natively instead, grab your platform from the latest release:

Platform	Options
	Installer (Sportarr-Setup.exe) installs it for you, or Portable (win-x64.zip) runs from a folder with no install.
	Apple Silicon (osx-arm64) for M1/M2/M3/M4 Macs, or Intel (osx-x64) for older Macs.
	x64 (linux-x64) for most servers, or ARM64 (linux-arm64) for Raspberry Pi and ARM boxes.

• Tracks events across all major sports (fighting sports, football, soccer, basketball, racing, etc.)
• Searches Usenet and torrent indexers automatically
• Manages quality upgrades when better releases become available
• Organizes files with customizable naming schemes
• Supports multi-part events (prelims, main cards) for fighting sports
• Integrates with Plex, Jellyfin, Emby for library updates
• Fetches subtitles through Bazarr
• Notifies you on grabs, imports, and health issues via Discord, ntfy, Apprise, webhooks, or custom scripts

version: "3.8"
services:
  sportarr:
    image: sportarr/sportarr:latest
    container_name: sportarr
    environment:
      - PUID=99
      - PGID=100
      - UMASK=022
      - TZ=America/New_York  # Optional: Set your timezone
    volumes:
      - /path/to/sportarr/config:/config
      - /path/to/sports:/data
    ports:
      - 1867:1867
    restart: unless-stopped

The /config volume stores your database and settings. The /data volume is your media library root folder.

After starting the container, access the web UI at http://your-server-ip:1867.

docker run -d \
  --name=sportarr \
  -e PUID=99 \
  -e PGID=100 \
  -e UMASK=022 \
  -e TZ=America/New_York \
  -p 1867:1867 \
  -v /path/to/sportarr/config:/config \
  -v /path/to/sports:/data \
  --restart unless-stopped \
  sportarr/sportarr:latest

• TrueNAS SCALE - Sportarr is in the community apps train. Search for "sportarr" on the Apps screen and install from there; catalog updates track new releases automatically.
• HexOS - Sportarr is in the curated apps catalog with the same one-click install.
• Unraid - search "sportarr" in Community Applications (community-maintained template, thanks tquizzle). Official templates live at Sportarr/unraid-templates.

Download the latest release from the releases page. Extract the archive for your platform and run the executable.

By default, configuration is stored in a data subdirectory where you run Sportarr from. You can specify a custom location using the -data argument:

# Windows
Sportarr.exe -data C:\ProgramData\Sportarr

# Linux/macOS
./Sportarr -data /var/lib/sportarr

Or set the Sportarr__DataPath environment variable:

# Linux/macOS
export Sportarr__DataPath=/var/lib/sportarr
./Sportarr

# Windows PowerShell
$env:Sportarr__DataPath = "C:\ProgramData\Sportarr"
.\Sportarr.exe

Priority order: Command-line -data argument > Environment variable > Default ./data

Sportarr uses SQLite by default - no configuration needed. If you already run a PostgreSQL cluster elsewhere in your setup, Sportarr can use it instead.

PostgreSQL support is for fresh installs only. There is no SQLite → PostgreSQL migration path. Pick your provider before your first run.

docker-compose.yml has the PostgreSQL environment variables included as commented-out lines you can uncomment to switch, and docker-compose.example.yml has a full working example using Docker secrets for the password instead of plaintext.

To use Postgres, set:

environment:
  - Sportarr__Database__Provider=postgres
  - Sportarr__Database__Host=postgres
  - Sportarr__Database__Port=5432
  - Sportarr__Database__Name=sportarr
  - Sportarr__Database__Username=sportarr
  - Sportarr__Database__Password=change-me

Any Sportarr__* environment variable can instead be supplied from a file (Docker secrets) by prefixing it with FILE__ and pointing the value at the file's path:

environment:
  - FILE__Sportarr__Database__Password=/run/secrets/sportarr_db_password
secrets:
  sportarr_db_password:
    file: ./secrets/sportarr_db_password.txt

Backup and restore work the same way on both providers (pg_dump/pg_restore for Postgres), but a backup can only be restored onto an install running the same provider it was created on.

1. Root Folder - Go to Settings > Media Management and add a root folder. This is where Sportarr will store your sports library.

   

2. Download Client - Settings > Download Clients. Add your download client (qBittorrent, Transmission, Deluge, rTorrent, uTorrent, SABnzbd, NZBGet, NZBdav, Decypharr, or a torrent/usenet blackhole folder). If using Docker, make sure both containers can access the same download path.

   

3. Indexers - Settings > Indexers. Add your Usenet indexers or torrent trackers. Sportarr supports Newznab and Torznab APIs, so Prowlarr integration works out of the box.

   

4. Add Content - Use the search to find leagues or events. Add them to your library and Sportarr will start monitoring.

   

   

   

Usenet: SABnzbd, NZBGet, NZBdav

Torrents: qBittorrent, Transmission, Deluge, rTorrent, uTorrent

Blackhole: Torrent Blackhole, Usenet Blackhole - Sportarr drops the grabbed .torrent/.nzb into a folder for any external downloader and imports the finished download from a watch folder, so you can keep your downloader independent of Sportarr.

Debrid/Proxy: Decypharr (torrents and usenet)

If you use Prowlarr, you can sync your indexers automatically:

1. In Prowlarr, go to Settings > Apps
2. Add Sonarr as an application (Sportarr isn't in Prowlarr yet, but the Sonarr option works)
3. Use http://localhost:1867 as the URL (or your actual IP/hostname)
4. Get your API key from Sportarr's Settings > General
5. Select TV (5000) categories for sync - this includes TV/HD (5040), TV/UHD (5045), and TV/Sport (5060)

Indexers will sync automatically and stay updated.

Bazarr can manage subtitles for your sports library. Add Sportarr in Bazarr exactly like you'd add Sonarr:

1. In Bazarr, go to Settings > Sonarr and enable it
2. Set the Address and Port to your Sportarr host (e.g. your server IP and 1867)
3. Paste your Sportarr API key (Settings > General), then test and save

Bazarr reads your leagues and events and searches for subtitles automatically.

Sportarr can notify you on grabs, imports, upgrades, and health issues. Configure providers in the Notifications settings:

• Discord and generic webhooks (with optional username/password auth and custom headers)
• ntfy (self-hosted or ntfy.sh)
• Apprise (one endpoint, 90+ services)
• Custom scripts (run any executable on events)

Sportarr uses a TV show-style naming convention that works well with Plex:

/data/Sports League/Season 2024/Sports League - s2024e12 - Event Title - 1080p.mkv

For fighting sports with multi-part episodes enabled:

Sports League - s2024e12 - pt1 - Event Title.mkv  (Early Prelims)
Sports League - s2024e12 - pt2 - Event Title.mkv  (Prelims)
Sports League - s2024e12 - pt3 - Event Title.mkv  (Main Card)

You can customize the naming format in Settings > Media Management.

Sportarr provides metadata agents for Plex, Jellyfin, and Emby that fetch posters, banners, descriptions, and episode organization from sportarr.net.

Sportarr supports two methods for Plex integration:

For Plex 1.43.0+, use the new Custom Metadata Provider system. No plugin installation required!

1. Open Plex Web and go to Settings → Metadata Agents
2. Click + Add Provider
3. Enter the URL: https://sportarr.net/plex
4. Click + Add Agent and give it a name (e.g., "Sportarr")
5. Restart Plex Media Server
6. Create a TV Shows library, select your sports folder, and choose the Sportarr agent

For older Plex versions, download the legacy bundle from Sportarr UI (Settings > General > Media Server Agents) and copy to your Plex Plug-ins directory. Note: Plex has announced legacy agents will be deprecated in 2026.

See agents/plex/README.md for detailed instructions and troubleshooting.

1. Build the plugin (requires .NET 9 SDK) or download from releases:

   cd agents/jellyfin/Sportarr
   dotnet build -c Release

2. Copy the DLL and meta.json to your Jellyfin plugins directory. The folder name must include the version (e.g. Sportarr_1.0.0):

   • Docker: /config/data/plugins/Sportarr_<version>/
   • Windows: %APPDATA%\Jellyfin\Server\plugins\Sportarr_<version>\
   • Linux: ~/.local/share/jellyfin/plugins/Sportarr_<version>/

3. Restart Jellyfin

4. Create a library: select Shows, add your sports folder, enable Sportarr under Metadata Downloaders

See agents/jellyfin/README.md for detailed instructions.

Emby works with the same metadata API as Jellyfin and Plex. Configure it using Open Media data sources:

1. In Emby, go to Settings → Server → Metadata

2. Under Open Media, add a new provider:

   • Name: Sportarr
   • URL: https://sportarr.net

3. Create a library for your sports content:

   • Select TV Shows as the content type
   • Add your sports media folder
   • Under Metadata Downloaders, enable Open Media and move Sportarr to the top

4. Refresh your library metadata to pull in sports event information

⚠️ ALPHA FEATURE WARNING: The IPTV DVR functionality is in very early alpha stage. Expect bugs, missing features, and poor functionality while this feature is being developed. Use at your own risk and please report any issues you encounter.

Sportarr includes experimental support for recording live sports events directly from IPTV streams using FFmpeg.

• IPTV Source Management - Add M3U playlists or Xtream Codes providers
• Channel-to-League Mapping - Map IPTV channels to leagues for automatic recording
• Automatic DVR Scheduling - When you monitor an event, Sportarr can automatically schedule a DVR recording if the league has a mapped channel
• FFmpeg Recording - Records IPTV streams in transport stream format
• Auto-Import - Completed recordings are automatically imported into your event library
• TV Guide - EPG-style grid showing channels and their programming with DVR recordings highlighted
• Filtered M3U/EPG Export - Serve filtered playlists and EPG data to external IPTV apps

• FFmpeg must be installed and accessible in your system PATH
• A working IPTV source (M3U playlist or Xtream Codes credentials)

• Recording quality depends entirely on your IPTV source
• Stream reconnection may not work reliably with all providers
• Limited error handling for stream failures
• No hardware acceleration support yet
• File size estimation is approximate

1. Go to Settings > IPTV Sources and add your M3U playlist URL or Xtream Codes provider

   

2. Go to Settings > IPTV Channels to view imported channels and map them to leagues

   

3. Go to Settings > DVR Recordings to configure recording settings and view scheduled/completed recordings

   

4. When you monitor an event, if its league has a mapped channel, a DVR recording will be automatically scheduled

The TV Guide provides an EPG-style grid view of your IPTV channels and their programming:

• EPG Sources - Add XMLTV EPG sources to populate channel programming
• Time-based Navigation - Browse programming in 6-hour increments
• Filters - Show only scheduled recordings, sports channels, or enabled channels
• DVR Integration - Scheduled recordings are highlighted in the guide
• Quick Scheduling - Click any program to view details and schedule a DVR recording

Access the TV Guide from IPTV > TV Guide in the navigation menu.

Sportarr can serve filtered M3U playlists and EPG data for use with external IPTV applications like TiviMate, IPTV Smarters, or other players:

• Filtered M3U - http://your-server:1867/api/iptv/filtered.m3u
• Filtered EPG - http://your-server:1867/api/iptv/filtered.xml

Optional query parameters:

• sportsOnly=true - Only include sports channels
• favoritesOnly=true - Only include favorite channels
• sourceId=X - Only include channels from a specific source

The filtered exports respect your channel settings - hidden channels are excluded, and only enabled channels are included. Find the subscription URLs in Settings > IPTV Sources under "External App Subscription URLs".

This feature is under active development. Feedback and bug reports are welcome!

Can't connect to download client in Docker? Use the container name (e.g., qbittorrent) instead of localhost. Make sure both containers are on the same Docker network.

Files not importing? Check that the download path is accessible from within the Sportarr container. The path your download client reports needs to be the same path Sportarr sees.

Indexer errors? Check your API keys and make sure you haven't hit rate limits. Logs are available in System > Logs.

• Discord - Best place for quick help
• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - General questions

Requires .NET 8 SDK and Node.js 20+.

git clone https://github.com/Sportarr/Sportarr.git
cd Sportarr

# Build (automatically builds frontend if Node.js is available)
dotnet build src/Sportarr.csproj

# Run
dotnet run --project src/Sportarr.csproj

The build process automatically:

1. Builds the React frontend (if npm is available)
2. Copies the frontend to wwwroot
3. Compiles the .NET backend

To skip the automatic frontend build (e.g., if you built it separately):

dotnet build src/Sportarr.csproj -p:SkipFrontendBuild=true

Sportarr is made better by everyone who has contributed code. Thank you.

BenjaminDecreusefond	ohathar	mmmmmtasty	FacePlant101	gwyden	abcattell91
gerrewsb	scottrobertson	afrancke	benjamin-decreusefond	Donai82	gilesw
hobbithau5	jpaull-nz	kristofferR	lustered	lyrova-andy	nathanjcollins
nickperkins	Percentnineteen	Pukabyte	schlort	skjaere	slflowfoon

_{See the full contributor graph, plus everyone helping with testing and bug reports on Discord.}

Sportarr is free and self-funded. If it saves you time, a one-time or monthly contribution keeps it moving, and every supporter shows up here.

GNU GPL v3 - see LICENSE.md

Sportarr is based on Sonarr. Thanks to the Sonarr team for the foundation.