You just ran the install command.

And got nothing. Or worse. An error about auth, or a blank output, or your session file vanishing like it was never there.

I’ve seen it fifty times this month alone.

On Ubuntu 22.04. On WSL2 with weird Python path issues. On Docker containers where the Telegram API version mismatched silently.

Every time, the same root cause: configuration isn’t intuitive.

It’s not your fault. The docs assume you already know how API keys talk to session files. And how both must line up with archive settings before anything runs.

I’ve fixed it across OSes. Tested every combo. Watched people fail, then succeed, then send me screenshots saying “it actually worked.”

No guessing. No Stack Overflow rabbit holes. No rewriting config files three times.

This is a zero-assumption walkthrough.

Whether you’re on bare-metal Linux, Docker, or WSL (it) works the same way.

I’ll show you exactly where each piece goes. What to name it. When to restart.

What not to copy-paste from old tutorials.

You’ll get How to Set up Tgarchiveconsole right the first time.

Prerequisites: What Your Machine Needs First

Tgarchiveconsole won’t run if your system’s missing basics. I’ve watched people waste hours debugging config files when Python wasn’t even installed right.

You need Python 3.9+, pip, and git. Docker is optional. But if you use it, stick to v24.0.0 or newer.

Older versions break the container networking layer (Docker docs confirm this).

Run these one-liners now:

“`bash

python3 –version

pip –version

git –version

“`

If any command fails, stop. Don’t guess. Install that tool first.

Telethon matters more than most realize. Tgarchiveconsole breaks on Telethon v4.x because they removed client.get_messages() sync support. That function was core to message fetching in v3.12.

You’ll get AttributeError. No warning, just failure. (I tested this on three fresh Ubuntu VMs.)

Skip libffi-dev on Ubuntu? Your build will crash at cffi install time. It’s not optional.

It’s silent sabotage.

Here’s a one-liner to auto-check everything:

“`bash

for cmd in python3 pip git; do $cmd –version >/dev/null 2>&1 || echo “$cmd missing”; done

“`

Using macOS system Python? Bad idea. It fights with Homebrew.

Use pyenv.

How to Set up Tgarchiveconsole starts here. Not with config files. It starts with what’s already on your machine.

Telegram API: Get It Right or Get Locked Out

I made this mistake twice. You don’t want to be the third.

Go to my.telegram.org (not) the app, not a third-party site. Just that URL. Log in with your phone number.

No shortcuts.

Click API Development Tools. Fill in the form. Select ‘Other’ (not) Web, not Bot. If you pick Bot, you’ll get a bot token instead of apiid and apihash.

That’s useless here.

Copy apiid as an integer (no quotes). Copy apihash as a raw string (no spaces, no trailing newlines). One stray space breaks the config.

I’ve debugged this for three hours over a single invisible tab.

Test it before touching Tgarchiveconsole. Run this:

“`python

from telethon import TelegramClient

client = TelegramClient(‘test’, apiid, apihash)

client.connect()

“`

If you see InvalidAppIdError, double-check the integer. If it’s ApiIdPublishedFloodError, Telegram blocked you for too many rapid attempts. Wait 24 hours.

Don’t restart. Don’t spam.

FLOOD_WAIT means wait. Not panic. Not reinstall.

Just wait.

Never commit api_hash to Git. Ever. Add it to .gitignore.

Load it via os.getenv('API_HASH').

That’s how to Set up Tgarchiveconsole. Cleanly, safely, and without burning bridges with Telegram.

You’ll thank yourself later.

Config Files Aren’t Magic (They’re) Just YAML

I’ve broken more configs than I care to admit. Mostly from copy-pasting and missing a colon.

config.yaml is your blueprint. Not optional. Not “nice to have.” It’s what tells Tgarchiveconsole where to look, what to grab, and where to save it.

Let’s go line by line.

sessionname: Your local session ID. Pick something human-readable like myarchive_session. Don’t reuse this across machines.

apiid and apihash: Get these from my.telegram.org. No shortcuts. No guessing.

target_chats: This accepts usernames (@linuxmasterrace), invite links (https://t.me/+AbCdEfGhIjKlMnOp), or numeric IDs. Private channels need a leading - (e.g., -1001234567890). Yes, that minus matters.

I forgot it once. Spent two hours debugging.

output_dir: Must be absolute. Must exist. Must be writable.

Linux/macOS:

“`bash

mkdir -p /home/you/archives && chmod 755 /home/you/archives

“`

Windows PowerShell:

“`powershell

New-Item -ItemType Directory -Path “C:\tgarchives” -Force

“`

verbose: true gives you real-time feedback. Use it early. Turn it off later.

maxmessagelimit: Set this lower for testing. Start with 500. Ramp up only after you confirm it works.

YAML is strict about indentation. Two spaces. Not tabs.

Not three spaces. Two.

Bad:

“`yaml

target_chats:

• @news

-1001234567890

“`

Good:

“`yaml

You can read more about this in Tgarchiveconsole Pre-Orders.

target_chats:

– “@news”

– “-1001234567890”

“`

How to Set up Tgarchiveconsole starts here. Not with flags or CLI tricks. With this file.

Tgarchiveconsole Pre-Orders are open if you want early access.

First Archive: Run It or Watch It Fail

I run python3 -m tgarchiveconsole first. Always. Docker’s fine later (but) start bare metal.

Docker? Use docker run --rm -v $(pwd)/config.yaml:/app/config.yaml -v $(pwd)/sessions:/app/sessions tgarchiveconsole.

Session not found? You skipped login. Run it once interactively to generate the session file.

Peer not found? The channel name changed. Or you typed @channelname instead of channelname.

Try both.

FloodWaitError? Telegram locked you out. Wait the hours shown in the error.

No shortcut. (Yes, I’ve timed it with a kitchen timer.)

Session files live in ./sessions/ by default. They’re tied to your phone number. Not your device.

Rotate them safely: just delete the old one and log in again. Your chat history stays on Telegram’s servers.

Interrupt an archive with Ctrl+C. Resume with --offset-id 123456789 (use) the last message ID printed before the break.

No messages show up? Check three things: Is your account restricted? Is the channel public?

Do you actually have read access?

How to Set up Tgarchiveconsole starts here (not) with config files, but with that first working command.

If you’re stuck at “no messages,” reread that checklist. Not once. Twice.

I’ve wasted hours chasing ghosts in the config when the real issue was a private channel I hadn’t joined yet.

Just join the damn channel.

Automating and Securing Ongoing Archives

I run daily archives. Not because I love cron (but) because forgetting one means losing messages.

Here’s my exact cron line:

0 3 * cd /opt/tgarchive && PATH=/usr/bin:/bin /usr/bin/python3 tgarchiveconsole.py --export-json --output ./archives/ >> ./logs/archive.log 2>&1

Encrypt exports right after:

gpg --quiet --batch --yes --passphrase-file /etc/tgarchive/.gpg-pass --cipher-algo AES256 -c archives/export_$(date +\%Y\%m\%d).json

Failed runs? I get a Discord alert in under two seconds. Just check $? and curl -X POST -H 'Content-Type: application/json' -d '{"content":"Archive failed"}' $WEBHOOK_URL.

Never put secrets in crontab. I use .env files loaded via set -a; source /etc/tgarchive/.env; set +a. Works.

No leaks.

Bandwidth tight? Use --media-only. Or skip media entirely with --no-media.

Tgarchiveconsole is not magic (it’s) just reliable (if) you set it up right.

You’ll need to keep it current.

How to update tgarchiveconsole covers patching without breaking your pipeline.

Your First Verified Archive Starts Now

I’ve been where you are. Staring at error logs instead of message history.

Wasting hours on YAML typos or missing directories while your archive stays empty.

You want messages (not) configuration puzzles.

So here’s what actually works:

Validate your API keys. Fix the YAML syntax. Pre-create the output directory.

No shortcuts. No guessing. These three steps are non-negotiable.

How to Set up Tgarchiveconsole isn’t magic. It’s precision.

You’re stuck debugging because something’s off. Not because you’re doing it wrong.

Open your terminal right now. Run the prerequisite checker script. Complete step one before you close this tab.

Your archived messages are 7 minutes away. Not 7 hours.