Linkarr - Media Organizer

Organize your media library with ease - without moving or duplicating your files!

• 📦 No file moving/copying: Monitors for changes, and then organizes your media with symlinks only.
• 🧲 Perfect for seeding/usenet: Works with files managed by torrent or usenet clients.
• 🎬 Jellyfin ready: Import organized folders directly into your media server.
• 🐳 Easy Docker deployment: Run anywhere, just map your folders.

Example:

	📂 Before (Source Folder)	📂 After (Organized Folder)
TV	/media/TV/ └─ 📂Show.Name.S01/     ├── Show.Name.S01E01.1080p.mkv     └── Show.Name.S01E02.1080p.mkv └─📂 Show.Name.S02/     ├── Show.Name.S02E01.1080p.mkv     └── Show.Name.S02E02.1080p.mkv └── Another.Show.Name.S04E07.1080p.mkv	/organized/TV/ └─🗂️ Show Name/     └─📂 Season 01/         ├─🔗 Show.Name.S01E01.1080p.mkv         └─🔗 Show.Name.S01E02.1080p.mkv     └─📂 Season 02/         ├─🔗 Show.Name.S02E01.1080p.mkv         └─🔗 Show.Name.S02E02.1080p.mkv └─🗂️ Another Show Name/     └─📂 Season 04/         └─🔗 Show.Name.S04E07.1080p.mkv
Movies	/media/Movies/ └─📂 Movie.Title.2023.1080p/     └── Movie.Title.2023.1080p.mkv └── Another.Movie.Title.2024.1080p.mkv	/organized/Movies/ └─📂 Movie Title (2023)/     └─🔗 Movie.Title.2023.1080p.mkv └─📂 Another Movie Title (2024)/     └─🔗 Another.Movie.Title.2024.1080p.mkv

---

Getting started

🚀 Docker Usage (Recommended)

You will need Docker installed on your system.

Important: You must map your source and destination folders to the same paths inside the container as on your host system. This ensures symlinks work correctly.

docker run -d \
  -v /path/to/source:/path/to/source \
  -v /path/to/organized:/path/to/organized \
  -v $(pwd)/config.json:/config/config.json \
  itsmejoeeey/linkarr:latest

Or with Docker Compose:

services:
  my-linkarr:
    image: itsmejoeeey/linkarr:latest
    container_name: linkarr
    # Pass in your config file below, by specifying the path on your host machine
    volumes:
      - /path/to/source:/path/to/source
      - /path/to/organized:/path/to/organized
      - ./config.json:/config/config.json
    restart: unless-stopped

See Configuration for details on configuring.

• Make sure to provide a valid config.json.
• Replace /path/to/source and /path/to/organized with your actual media paths.

Running manually

1. Install dependencies:

   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

2. Copy and edit the example config:

   cp config.example.json config.json
   # Edit config.json to match your source/destination folders and preferences
   

3. Run the organizer:

   cd src
   python -m linkarr.main ../config.json
   

Configuration

See config.example.json and src/linkarr/config.schema.json for configuration options.

Development

See here for further information.