Symlink Media Backup

A Python script designed for Windows users to create efficient, automated, versioned, and rotated backups of a virtual media library structure built with symbolic links.

This tool is the perfect solution for managing media collections from read-only sources, such as a cloud drive mounted with rclone or a Debrid service mounted with Zurg.

---

Features

• External configuration via a user-editable config.ini file.
• Interactive setup wizard for initial configuration on first run.
• Automatic UAC prompt to ensure necessary Administrator privileges.
• True symlink-aware backups using robocopy /SL and the TAR archive format.
• Automated filename versioning to prevent overwriting same-day backups.
• Configurable backup rotation based on file modification time.
• Pre-run validation of all required paths and executables.

The Problem It Solves

Because the symlink library resides on a standard writable drive, all media server features work out-of-the-box. This includes automatic subtitle downloading from Plex/Emby, local metadata saving by Jellyfin, and easy management of custom artwork and .nfo files directly within your library folders—no complex 'sidecar' directory configurations required."

Why Use Symlinks Instead of .strm Files?

This project uses a symbolic link structure pointing to a persistent virtual drive path (e.g., Z:...) instead of generating .strm files with direct HTTP links. This architectural choice provides two major benefits:

Backup Longevity: Symlinks point to a path that never expires. A backup of your library structure will remain valid indefinitely, unlike backups of .strm files containing temporary Debrid links that expire within hours or days.

API Efficiency: API calls to the Debrid service are only made on-demand at the moment of playback by the mounting tool (rclone/Zurg). Your library does not require a constantly running service to poll and refresh expiring links, drastically reducing API usage.

Requirements

• OS: Windows 10 / 11.
• Python: Python 3.8+ installed. It is crucial to check the "Add Python to PATH" option during installation.
• 7-Zip: Required by the backup.py script. The script defaults to the standard installation path (C:\Program Files\7-Zip\7z.exe), but this can be changed in config.ini.
• tar: Required by the restore.py script. tar.exe is included by default in modern Windows 10/11 and should be available in the system's PATH.
• A Mounted Virtual Drive: An active media source, like a drive mounted with rclone or Zurg, is needed for the restored symlinks to be functional.
• (Pre-Setup) A Symlink Library: This script suite manages an existing symlink library. You need to create this structure first using a tool like FileBot or TinyMediaManager.
• (Recommended) Developer Mode: For the most reliable symbolic link creation on Windows, it is highly recommended to enable Developer Mode in the Windows Settings. While running scripts with Administrator privileges often suffices, Developer Mode grants the necessary permissions to create symlinks even to non-elevated processes, preventing many common permission errors with other tools.

Installation & Usage

Backup Script (backup.py)

1. Download the backup.py script and place it in a permanent folder.
2. Double-click backup.py.
3. The script will detect that it's the first run and launch a setup wizard.
4. Answer the questions to provide your required paths.
5. A config.ini file will be created, and the first backup will run. All future runs will be automatic.

Restore Script (restore.py)

1. Double-click restore.py.
2. The script will ask for Administrator permission (UAC prompt). Click "Yes".
3. A file selection window will open. Choose the .tar backup file you wish to restore.
4. A folder selection window will open. Choose the destination folder for the restore.
5. The script will then extract the backup. For the restored links to work, ensure your virtual drive (e.g., Z:) is active.

Disclaimer

This tool is intended for use with legally owned or accessed media. The user is solely responsible for ensuring they comply with all applicable copyright laws.