immich/docs/docs/guides/remove-offline-files.md

Remove Offline Files [Community]

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

:::note Before running the script, please make sure you have a backup of your assets and database. :::

:::info None of the scripts can delete orphaned files from the external library. :::

This page is a guide to get rid of offline files from the repair page.

This way works by retrieving a file that contains a list of all the files that are defined as offline files, running a script that uses the Immich API in order to remove the offline files.

1. Create an API key under Admin User -> Account Settings -> API Keys -> New API Key -> Copy to clipboard.
2. Copy and save the code to file -> Immich Remove Offline Files.py.
3. Run the script and follow the instructions.

:::note You might need to run pip install halo tabulate tqdm if these dependencies are missing on your machine. :::

#!/usr/bin/env python3

# Note: you might need to run "pip install halo tabulate tqdm" if these dependencies are missing on your machine

import argparse
import json
import requests

from datetime import datetime
from halo import Halo
from tabulate import tabulate
from tqdm import tqdm
from urllib.parse import urlparse

def parse_arguments():
    parser = argparse.ArgumentParser(description='Fetch file report and delete orphaned media assets from Immich.')
    parser.add_argument('--apikey', help='Immich API key for authentication')
    parser.add_argument('--immichaddress', help='Full address for Immich, including protocol and port')
    parser.add_argument('--no_prompt', action='store_true', help='Delete orphaned media assets without confirmation')
    args = parser.parse_args()
    return args

def filter_entities(response_json, entity_type):
    return [
        {'pathValue': entity['pathValue'], 'entityId': entity['entityId'], 'entityType': entity['entityType']}
        for entity in response_json.get('orphans', []) if entity.get('entityType') == entity_type
    ]

def main():
    args = parse_arguments()
    try:
        if args.apikey:
            api_key = args.apikey
        else:
            api_key = input('Enter the Immich API key: ')

        if args.immichaddress:
            immich_server = args.immichaddress
        else:
            immich_server = input('Enter the full web address for Immich, including protocol and port: ')
        immich_parsed_url = urlparse(immich_server)
        base_url = f'{immich_parsed_url.scheme}://{immich_parsed_url.netloc}'
        api_url = f'{base_url}/api'
        file_report_url = api_url + '/audit/file-report'
        headers = {'x-api-key': api_key}

        print()
        spinner = Halo(text='Retrieving list of orphaned media assets...', spinner='dots')
        spinner.start()

        try:
            response = requests.get(file_report_url, headers=headers)
            response.raise_for_status()
            spinner.succeed('Success!')
        except requests.exceptions.RequestException as e:
            spinner.fail(f'Failed to fetch assets: {str(e)}')

        person_assets = filter_entities(response.json(), 'person')
        orphan_media_assets = filter_entities(response.json(), 'asset')

        num_entries = len(orphan_media_assets)

        if num_entries == 0:
            print('No orphaned media assets found; exiting.')
            return

        else:
            if not args.no_prompt:
                table_data = []
                for asset in orphan_media_assets:
                    table_data.append([asset['pathValue'], asset['entityId']])
                print(tabulate(table_data, headers=['Path Value', 'Entity ID'], tablefmt='pretty'))
                print()

                if person_assets:
                    print('Found orphaned person assets! Please run the "RECOGNIZE FACES > ALL" job in Immich after running this tool to correct this.')
                    print()

                if num_entries > 0:
                    summary = f'There {"is" if num_entries == 1 else "are"} {num_entries} orphaned media asset{"s" if num_entries != 1 else ""}. Would you like to delete {"them" if num_entries != 1 else "it"} from Immich? (yes/no): '
                    user_input = input(summary).lower()
                    print()

                    if user_input not in ('y', 'yes'):
                        print('Exiting without making any changes.')
                        return

            with tqdm(total=num_entries, desc="Deleting orphaned media assets", unit="asset") as progress_bar:
                for asset in orphan_media_assets:
                    entity_id = asset['entityId']
                    asset_url = f'{api_url}/asset'
                    delete_payload = json.dumps({'force': True, 'ids': [entity_id]})
                    headers = {'Content-Type': 'application/json', 'x-api-key': api_key}
                    response = requests.delete(asset_url, headers=headers, data=delete_payload)
                    response.raise_for_status()
                    progress_bar.set_postfix_str(entity_id)
                    progress_bar.update(1)
            print()
            print('Orphaned media assets deleted successfully!')
    except Exception as e:
        print()
        print(f"An error occurred: {str(e)}")

if __name__ == '__main__':
    main()

Thanks to DooMRunneR and Sircharlo for writing this script.

This way works by downloading a JSON file that contains a list of all the files that are defined as offline files, running a script that uses the Immich API in order to remove the offline files.

1. Create an API key under Admin User -> Account Settings -> API Keys -> New API Key -> Copy to clipboard.
2. Download the JSON file under Administration -> repair -> Export.
3. Replace YOUR_IP_HERE and YOUR_API_KEY_HERE with your actual IP address and API key in the script.
4. Run the script in the same folder where the JSON file is located.

Script for Linux based systems:

awk -F\" '/entityId/ {print $4}' orphans.json | while read line; do curl --location --request DELETE 'http://YOUR_IP_HERE:2283/api/asset' --header 'Content- Type: application/json' --header 'x-api-key: YOUR_API_KEY_HERE' --data '{ "force": true, "ids": ["'"$line"'"]}';done

Script for the Windows system (run through PowerShell):

Get-Content orphans.json | Select-String -Pattern 'entityId' | ForEach-Object {
  $line = $_ -split '"' | Select-Object -Index 3
  $body = [pscustomobject]@{
    'ids' = @($line)
    'force' = (' true ' | ConvertFrom-Json)
  } | ConvertTo-Json -Depth 3
  Invoke-RestMethod -Uri 'http://YOUR_IP_HERE:2283/api/asset' -Method Delete -Headers @{
    'Content-Type' = 'application/json'
    'x-api-key' = 'YOUR_API_KEY_HERE'
  } -Body $body
}

Thanks to DooMRunneR for writing this script.