Prerequisites
- Docker with the Compose plugin (v2)
- Dispatcharr — Teamarr is designed around tight integration with Dispatcharr and requires it to create and manage channels
Docker Compose setup
Create a docker-compose.yml file:
services:
teamarr:
image: ghcr.io/pharaoh-labs/teamarr:latest
container_name: teamarr
restart: unless-stopped
ports:
- 9195:9195
volumes:
- ./data:/app/data
environment:
# Timezone for the Teamarr web UI
# EPG output timezone is configured separately in Settings
- TZ=America/New_York
# Console log level: DEBUG, INFO, WARNING, ERROR (default: INFO)
# Note: File logging (data/logs/) always captures DEBUG regardless of this setting
# - LOG_LEVEL=INFO
# Log format: "text" or "json" (default: text)
# Use "json" for log aggregation systems (ELK, Loki, Splunk)
# - LOG_FORMAT=text
# Log directory (default: /app/data/logs)
# - LOG_DIR=/app/data/logs
# ESPN API tuning — reduce if you experience timeouts (e.g., PiHole, AdGuard)
# - ESPN_MAX_WORKERS=100
# - ESPN_MAX_CONNECTIONS=100
# - ESPN_TIMEOUT=10
# - ESPN_RETRY_COUNT=3
# Skip team/league cache refresh on startup (default: false)
# Cache can still be refreshed manually via the UI or the daily scheduled task.
# - SKIP_CACHE_REFRESH=true
http://<your-server>:9195.
Environment variables
| Variable | Default | Description |
|---|
TZ | UTC | Timezone for the Teamarr web interface. EPG output timezone is set separately in Settings. |
LOG_LEVEL | INFO | Console log level. One of DEBUG, INFO, WARNING, ERROR. File logs always capture DEBUG. |
LOG_FORMAT | text | Log output format. Use json for log aggregation systems (ELK, Loki, Splunk). |
LOG_DIR | /app/data/logs | Override the log directory path. |
ESPN_MAX_WORKERS | 100 | Parallel workers for ESPN team/event processing. Reduce if you experience DNS throttling. |
ESPN_MAX_CONNECTIONS | 100 | ESPN HTTP connection pool size. |
ESPN_TIMEOUT | 10 | ESPN request timeout in seconds. |
ESPN_RETRY_COUNT | 3 | Number of retry attempts for failed ESPN requests. |
SKIP_CACHE_REFRESH | false | Skip the team/league cache refresh on startup. Useful for faster restarts during development. |
| Tag | Description |
|---|
latest | Stable release — recommended for production use |
dev | Development builds — may contain experimental or incomplete features |
1.4.9-archive | Final 1.x release — no longer maintained, no future updates |
There is no automatic migration path from 1.x to 2.x. If you are running a 1.x installation, Teamarr will detect the legacy database on startup and guide you through downloading a backup before starting fresh. To stay on 1.x, pin the 1.4.9-archive tag.
Unraid
An Unraid Docker template is available in the Community Applications store. Search for Teamarr and install directly from the Unraid UI — no manual compose file needed.
Data persistence
All Teamarr data lives inside the ./data volume mount (/app/data inside the container):
| Path | Contents |
|---|
data/teamarr.db | SQLite database — teams, templates, settings, event groups, and generation history |
data/logs/ | Rotating log files (teamarr.log and teamarr_errors.log), auto-managed |
data/epg/ | Generated XMLTV output files consumed by Dispatcharr |
Never delete teamarr.db. It contains all your configured teams, templates, settings, and history. Schema upgrades between versions are handled automatically through migrations on startup — deleting the database is never required and will cause permanent data loss.
First run behavior
On the first startup, Teamarr:
- Creates the SQLite database and runs all schema migrations
- Refreshes the league and team cache from ESPN, HockeyTech, MLB Stats, and TheSportsDB (approximately 2–3 minutes)
- Starts the web UI on port
9195
The dashboard displays a Getting Started guide walking you through the initial configuration: connecting to Dispatcharr, creating templates, and adding teams or event groups. The guide is replaced by statistics and generation history once you have at least one template and either teams or event groups configured.
Updating
Pull the latest image and recreate the container:
docker compose pull teamarr
docker compose up -d teamarr