Subsarr

March 17, 2026 · View on GitHub

Subscene shut down in 2023, taking millions of community subtitles with it. subsarr lets you self-host the full Subscene archive and use it as a subtitle source in Bazarr — so your media server can automatically find and download subtitles without depending on any external service.

It imports the community-preserved Subscene V2 dump (~2.7 million entries) into a local database and exposes a search API that Bazarr can query by IMDB ID, title, language, season/episode, and more.

Features

Configurable database — SQLite (default), PostgreSQL, or MySQL/MariaDB
Configurable storage — local filesystem (default) or any S3-compatible object store
No authentication required — simple read-only subtitle API
Streaming import — reads directly from the 7z archive, no extraction needed
Single binary — statically compiled Go with zero runtime dependencies

Getting started

Step 1 — Get the archive

The full Subscene V2 dump (~97 GB, 12-part split 7z) was preserved and shared by the community on Reddit:

r/DataHoarder — "Subscene.com full dump" https://www.reddit.com/r/DataHoarder/comments/1b5rxc2/subscenecom_full_dump/

Download all 12 parts (Subscene V2.7z.001 … Subscene V2.7z.012) into the same directory. The importer reads them as a single split archive — no extraction needed.

Step 2 — Import the dump

This is a one-time step. The import streams directly from the archive and takes roughly 2–3 hours for the full dataset.

docker run --rm \
  -v /srv/subsarr/db:/app/db \
  -v /mnt/array/subsarr/storage:/app/storage \
  -v /path/to/subscene/archive:/tmp/subscene-archive \
  ghcr.io/slimcdk/subsarr:latest \
  import-dump --archive "/tmp/subscene-archive/Subscene V2.7z.001"

Progress is printed to stdout:

[import] opening archive /tmp/subscene-archive/Subscene V2.7z.001 …
[import] archive has 2706833 entries across volumes: [...]
[import] detected format: v2
[import] 10000 processed  9987 imported  0 skipped  13 errors  (312/s)
...
[import:V2 stream] done: 2706833 processed  2695441 imported  ...  in 2h28m

Step 3 — Run the server

docker run -d \
  --name subsarr \
  --restart unless-stopped \
  -v /srv/subsarr/db:/app/db \
  -v /mnt/array/subsarr/storage:/app/storage \
  -p 8090:8090 \
  ghcr.io/slimcdk/subsarr:latest

The API is available at http://localhost:8090/api/v1/.

Docker Compose

# docker-compose.yml
services:
  subsarr:
    image: ghcr.io/slimcdk/subsarr:latest
    volumes:
      - /mnt/cache/subsarr/db:/app/db           # SSD/cache — fast reads
      - /mnt/array/subsarr/storage:/app/storage  # array — bulk file storage
      - /path/to/subscene/archive:/tmp/subscene-archive:ro
    ports:
      - 8090:8090
    restart: unless-stopped

# Import (one-time)
docker compose run --rm subsarr import-dump --archive "/tmp/subscene-archive/Subscene V2.7z.001"

# Start the server
docker compose up -d

Configuration

All settings are via environment variables. Defaults are tuned for the simplest setup (SQLite + local filesystem).

Variable	Default	Description
`SUBSARR_DB_DRIVER`	`sqlite`	Database backend: `sqlite`, `postgres`, or `mysql`
`SUBSARR_DB_DSN`	`subsarr.db`	Connection string (file path for SQLite, URL for others)
`SUBSARR_STORAGE_BACKEND`	`filesystem`	File storage: `filesystem` or `s3`
`SUBSARR_STORAGE_PATH`	`./storage`	Local filesystem root (when backend=filesystem)
`SUBSARR_S3_ENDPOINT`		S3-compatible endpoint URL
`SUBSARR_S3_BUCKET`	`subsarr`	S3 bucket name
`SUBSARR_S3_REGION`	`us-east-1`	S3 region
`SUBSARR_S3_ACCESS_KEY`		S3 access key
`SUBSARR_S3_SECRET_KEY`		S3 secret key
`SUBSARR_S3_PATH_STYLE`	`false`	Use path-style S3 URLs (required for most self-hosted S3)
`SUBSARR_LISTEN`	`0.0.0.0:8090`	HTTP listen address

Example: PostgreSQL + S3

services:
  subsarr:
    image: ghcr.io/slimcdk/subsarr:latest
    environment:
      SUBSARR_DB_DRIVER: postgres
      SUBSARR_DB_DSN: postgres://user:pass@postgres:5432/subsarr?sslmode=disable
      SUBSARR_STORAGE_BACKEND: s3
      SUBSARR_S3_ENDPOINT: http://s3:3900
      SUBSARR_S3_BUCKET: subsarr
      SUBSARR_S3_ACCESS_KEY: your-access-key
      SUBSARR_S3_SECRET_KEY: your-secret-key
      SUBSARR_S3_PATH_STYLE: "true"
    ports:
      - 8090:8090

API

Endpoint	Description
`GET /api/v1/info`	Provider metadata and capabilities
`GET /api/v1/languages`	Available languages with counts
`GET /api/v1/subtitles/search`	Search subtitles (see params below)
`GET /api/v1/subtitles/{id}/download`	Download a subtitle file

Search parameters

Param	Example	Description
`imdb_id`	`tt0468569`	Filter by IMDB ID
`language`	`English`	Filter by language name
`slug`	`the-dark-knight`	Filter by Subscene slug
`query`	`dark knight`	Free-text search on title/filename
`hi`	`true`	Hearing-impaired only
`year`	`2008`	Filter by release year
`season`	`2`	Filter by season number (S02 pattern)
`episode`	`5`	Combined with season for S02E05 pattern
`page`	`1`	Page number (1-based)
`per_page`	`50`	Results per page (max 200)

Development

# Build
make build

# Run server
make run

# Run tests
make test

# Build Docker image
make docker-build

sqlc

Database queries are managed with sqlc. Schema and query files are in sql/. To regenerate Go code after modifying queries:

sqlc generate