teledrive_restore

Warning

Use at your own risk. This script has not been thoroughly tested. Always make sure you have a backup of your files before running it, especially with the mv (move) operation. The author takes no responsibility for any data loss or damage caused by the use of this script.

A command-line utility to restore files from a flat TeleDrive export dump back into their original folder hierarchy, using the metadata exported from TeleDrive as a files.json file.

Requirements

• Python 3.6 or newer (no third-party packages required)

Background

TeleDrive stores all uploaded files in Telegram as flat message attachments. When you export your data, you get:

1. A files.json metadata file describing every file and folder, including parent-child relationships.
2. A flat directory of downloaded files, all sitting in the same folder.

This script reads the metadata and reconstructs the full directory tree, placing every file in its correct folder.

Usage

python3 teledrive_restore.py <operation> <files_json> <source_dir> <dest_dir>

Arguments

Argument	Description
operation	mv to move files, or cp to copy files
files_json	Full path to the TeleDrive JSON export (any filename is accepted)
source_dir	Path to the flat directory containing all your downloaded TeleDrive files
dest_dir	Path to the root destination directory where the folder tree will be created

Help

python3 teledrive_restore.py --help

Examples

Copy all files into a restored tree (original flat dump is kept intact):

python3 teledrive_restore.py cp /home/user/files.json /mnt/teledrive_dump /mnt/restored

Move all files into a restored tree:

python3 teledrive_restore.py mv /home/user/files.json /mnt/teledrive_dump /mnt/restored

Behaviour

• The destination directory is created automatically if it does not exist.
• Nested folders of arbitrary depth are supported.
• Files at the root level (no parent folder) are placed directly in dest_dir.
• If a file cannot be found in source_dir, a WARNING is printed and the script continues with the next file.
• If a file already exists at the destination, a WARNING is printed and the file is skipped.
• A summary of moved/copied, missing, and skipped files is printed at the end.

Output example

Loaded 6800 entries from /home/user/files.json
Files to process: 5440
WARNING: File not found in source, skipping: some_missing_file.pdf
...

--- Summary ---
Copied: 5438
Missing (not found in source): 1
Skipped (already at destination): 1

License

Copyright (C) 2026 Anders da Silva Rytter Hansen, PC-Rytteren ApS

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

See the LICENSE file for the full license text.