tg-export 1.2.1

Flexible Telegram data export tool

tg-export

Экспорт данных из Telegram на локальный диск с гибкой настройкой.

Содержание

• Возможности
• Сценарии использования
• Установка
• Быстрый старт
• Структура конфигов
• Документация
• Тесты
• Разработка

Возможности

• Инкрементальный экспорт -- при повторном запуске скачиваются только новые сообщения и файлы, состояние хранится в SQLite
• Sibling-дедупликация -- при экспорте нескольких аккаунтов (семья, рабочий/личный) общие файлы не скачиваются повторно, а линкуются через hardlink
• Импорт из tdesktop -- файлы из стандартного экспорта Telegram Desktop копируются вместо повторного скачивания
• Takeout API -- использует официальный Takeout для обхода rate-limiting
• Гибкие правила экспорта -- настройка по чатам, папкам, типам (personal, groups, channels, bots), с фильтрами по датам, типам медиа и размеру файлов
• Логика архивных чатов -- чат считается архивным (is_archived) только если он присутствует исключительно в архиве Telegram. Если чат есть в основном списке диалогов или в именованной папке, он не помечается как архивный, даже если одновременно находится в архиве
• Проверка размера в runtime -- если реальный размер файла превышает лимит, скачивание прерывается и частичный файл удаляется
• HTML-рендеринг по месяцам -- каждый месяц в отдельном файле, с оглавлением (TOC) и навигацией prev/next
• Progress bars -- основной прогресс по сообщениям + sub-progress bars для каждого скачиваемого файла
• Контроль свободного места -- экспорт останавливается, если свободное место на диске падает ниже порога (min_free_space в config.yaml, по умолчанию 20 GB)
• Корректный shutdown -- Ctrl+C сохраняет состояние, двойной Ctrl+C -- force shutdown с cleanup
• Поддержка прокси -- SOCKS5, SOCKS4, HTTP прокси для подключения к Telegram API
• Данные в SQLite -- все сообщения и метаданные хранятся в SQLite, что позволяет пересоздать HTML без обращения к Telegram API, строить поисковые индексы, подключить веб-интерфейс или использовать данные в любых других целях
• CLI для анализа -- команда tg info для batch-запросов информации о чатах через API
• Очистка данных чата -- команда purge для удаления данных конкретного чата из БД и с диска

Сценарии использования

Личный архив -- экспорт всех личных переписок и групп с медиафайлами на локальный диск для долгосрочного хранения.

Семейный экспорт -- экспорт аккаунтов нескольких членов семьи. Общие группы и каналы содержат одинаковые файлы -- sibling-дедупликация экономит место на диске через hardlink.

Выборочный экспорт -- экспорт только нужных чатов/папок с правилами: рабочие чаты экспортируются, боты и публичные каналы пропускаются, для флудилок скачиваются только фото.

Миграция с tdesktop -- если уже есть экспорт из Telegram Desktop, файлы из него импортируются без повторного скачивания.

Установка

Из PyPI:

pip install tg-export

Для работы через прокси:

pip install tg-export[proxy]

Из исходников:

uv pip install -e .

Быстрый старт

1. Получить API credentials

Зайти на my.telegram.org, создать приложение, получить api_id и api_hash.

uv run tg-export auth credentials

Ввести api_id и api_hash. Они сохраняются в ~/.config/tg-export/api_credentials.yaml и используются для всех аккаунтов.

2. Настроить прокси (если нужен)

Создать файл ~/.config/tg-export/config.yaml:

proxy:
  type: socks5      # socks5, socks4, http
  host: 127.0.0.1
  port: 1080
  # username: user   # опционально
  # password: pass   # опционально

3. Залогиниться в Telegram

uv run tg-export auth add --name myaccount

Ввести номер телефона и код подтверждения. Сессия сохранится в ~/.config/tg-export/sessions/myaccount.session.

Для нескольких аккаунтов повторить с разными именами. Установить аккаунт по умолчанию:

uv run tg-export account default myaccount

4. Анализ чатов и каталог

Получить каталог всех чатов аккаунта:

uv run tg-export list --output catalog.yaml
uv run tg-export list --format json --output catalog.json

Посмотреть информацию о конкретных чатах (количество сообщений, последние сообщения):

uv run tg-export info 123456789 987654321
uv run tg-export info --from-catalog catalog.json --type personal --last 3

5. Настройка правил экспорта

Сгенерировать шаблон конфига:

uv run tg-export init

Конфиг создается в ~/.config/tg-export/myaccount.yaml. Настроить правила: какие чаты экспортировать, какие пропускать, какие типы медиа скачивать.

AI-агенты (Claude Code, Cursor и т.д.) могут помочь с настройкой: показать список чатов по категориям, задать вопросы о каждом и сформировать конфиг интерактивно.

Пример конфига:

output:
  path: ./export_output/myaccount

defaults:
  media:
    types: [all]
    max_file_size: 100MB
    concurrent_downloads: 3

# Импорт файлов из существующего экспорта tdesktop
import_existing:
  - path: ~/Downloads/Telegram Desktop/DataExport
    type: tdesktop

# Правила по типам чатов
type_rules:
  bots:
    skip: true
  public:
    skip: true
  personal: {}    # экспортировать все личные чаты
  self: {}        # экспортировать Saved Messages

# Правила по папкам Telegram
folders:
  Work: {}
  Family:
    media:
      types: [photo, video]

# Правила по конкретным чатам
chats:
  - id: 777000
    name: Telegram
    action: skip
  - id: 123456789
    name: "Important Chat"
    media:
      types: []    # без медиа

# Что делать с чатами, не попавшими ни в одно правило
unmatched: skip

6. Запустить экспорт

uv run tg-export run

Для пробного запуска без скачивания:

uv run tg-export run --dry-run

При повторном запуске скачиваются только новые сообщения (инкрементальный экспорт).

7. Sibling-дедупликация

При экспорте нескольких аккаунтов в один каталог (./export_output/), tg-export автоматически находит соседние базы данных и использует уже скачанные файлы через hardlink:

export_output/
  account1/         # первый аккаунт
  account2/         # файлы из общих чатов линкуются из account1

Структура конфигов

~/.config/tg-export/
  api_credentials.yaml      # API ID и Hash (общие для всех аккаунтов)
  config.yaml               # Глобальные настройки (proxy, min_free_space)
  default_account            # Имя аккаунта по умолчанию
  sessions/
    myaccount.session        # Telethon-сессия
  myaccount.yaml             # Конфиг экспорта для аккаунта

export_output/
  myaccount/
    .tg-export-state.db      # SQLite: состояние экспорта, сообщения, файлы
    unfiled/
      Chat_Name_123456/
        messages.html         # Redirect на первый месяц
        messages_2024-01.html # Сообщения за январь 2024
        messages_2024-02.html # Сообщения за февраль 2024
        photos/               # Скачанные фото
        videos/               # Скачанные видео
        files/                # Скачанные документы
    folders/
      Work/
        ...

Документация

• docs/configuration.md -- подробное описание YAML-конфигурации экспорта (правила, фильтры, типы медиа, настройки выгрузки).
• CHANGELOG.md -- список изменений между версиями.
• CONTRIBUTING.md -- руководство для контрибьюторов: установка dev-окружения, запуск тестов, формат коммитов.

Тесты

uv run python -m pytest tests/ -v

Разработка

Установка dev-зависимостей:

uv sync --extra dev

Запуск тестов:

uv run python -m pytest

Подробнее -- в CONTRIBUTING.md.

Лицензия

MIT License