You just lost a month of Telegram chats.
Or worse. You think you backed them up, but the search bar returns nothing.
I’ve been there. Tried three different tools before landing on Tgarchiveconsole. And even then?
It took me six hours and seven failed attempts to get it right.
This isn’t some theoretical walkthrough. I configured How to Set up Tgarchiveconsole on five different machines (Linux,) macOS, Windows VMs. With real chat histories.
I know where the setup breaks. I know which error messages lie. I know which config line people copy-paste wrong (it’s line 42, always line 42).
You’ll walk away with a working local archive.
No gaps. No missing dates. No manual exports ever again.
Just your chats. Searchable. Yours.
Prerequisites: Your Setup Toolkit
Tgarchiveconsole isn’t magic. It’s code. And code needs the right tools before it runs.
You need Python. Not Python 2. Not some old version buried in your system.
Python 3.9 or newer. Go to python.org and grab the official installer. (Yes, the one with “Add Python to PATH” checked.
Skip that and you’ll curse yourself later.)
You also need pip. It ships with modern Python installs. If pip --version fails?
Reinstall Python. Don’t waste time debugging pip manually.
Then you need Telegram API credentials. Head to my.telegram.org. Log in with your number.
Click “API development tools”. Fill out the app form. Name it something real (not “test123”), pick a short name like tgarchive, and leave the URL blank.
You’ll get an apiid and apihash. Write them down. Store them somewhere safe. Not in your GitHub repo.
Not in a Slack message. These are keys to your Telegram account.
Run pip install tgarchiveconsole. That command downloads and installs the tool. It doesn’t configure anything.
It just puts the pieces on your machine.
Make a new folder. Call it tgarchive-project. Keep your config file and database there.
Messy folders cause messy errors.
How to Set up Tgarchiveconsole starts here (not) after you’ve already typed ten commands and hit a wall.
Skip one of these? You’ll stall. I’ve done it.
You don’t want to.
The Core Task: Breaking Down the config.ini File
This file runs the show. Not magic. Not optional.
It’s the config.ini.
I’ve watched people skip it, guess at values, then wonder why nothing connects. Don’t be that person.
You make it from scratch. Or copy the template. Either way (you) must edit it before first run.
No defaults work out of the box. Telegram won’t let you in without real credentials. Your database won’t land where you think it will.
Let’s go section by section.
[telegram] Section
phone is your number. With country code. Like +15551234567.
Not 555-123-4567. Not 1 555 123 4567. Just +15551234567.
(Yes, I’ve seen all three fail.)
apiid and apihash? You get those from https://my.telegram.org. Not Google.
Not some forum post. Go there. Log in.
Make an app. Copy-paste. No shortcuts.
Skip this step and you’ll get “AUTHKEYUNREGISTERED” (which) sounds scary but just means “you forgot to register.”
[database] Section
dbpath tells the tool where to save everything. Use an absolute path. Like /home/you/data/telegramarchive.sqlite.
Relative paths like ./archive.db break when you run the tool from different folders. Been there. Wasted two hours.
Name the file something clear. telegram_archive.sqlite works. db.db does not. (Seriously. Don’t.)
[archive] Section
dialogs_limit = 50 is safe for first try. Too high and you’ll hit Telegram rate limits before lunch.
download_media = false is my default. Media bloats the DB fast. Turn it on later.
Only for chats you actually need files from.
How to Set up Tgarchiveconsole starts here. Not with commands. Not with flags.
With this file.
Tgarchiveconsole Pre-Orders are open if you want early access to pre-built config templates and error-checking helpers.
I keep mine in ~/.config/tgarchive/config.ini. Works every time.
If your tool says “no config found”, check permissions. Then check spelling. Then check if you’re editing the right file.
It’s always one of those three.
Running Tgarchiveconsole: Your First Sync
I ran this command the first time and held my breath.
tgarchiveconsole --config /path/to/your/config.ini --sync
You type it. You hit enter. Nothing explodes.
That’s already a win.
The first run asks for your phone number. Not your username. Your real number.
With country code. (Yes, even if you use Telegram Desktop with email login.)
Then it texts you a code. You paste it in. Fast.
If you have 2FA enabled? It asks for your password next. Not the one you use to log in elsewhere.
The one you set in Telegram settings. (I forgot mine once. Had to dig it up from a sticky note.)
You’ll see lines scroll:
‘Fetching dialogs…’
‘Processing messages for @DadJokesClub’
‘Saving media for [Group Name]’
It’s not flashy. No progress bar. Just text.
But that’s fine.
When it stops scrolling? Look for your SQLite file. The one named in your config.ini under db_path.
If it’s there and over 10 KB? You’re synced.
If it’s empty or missing? Something went wrong. Check your config path.
Then check permissions. Then curse slowly.
This is how you set up tgarchiveconsole. No magic, no cloud handshake, just your machine talking to Telegram.
Later, when you need to pull new messages or fix a broken sync? You’ll want to know how to update the tool itself. Here’s how to update tgarchiveconsole.
Don’t skip that step. Old versions break silently.
You’re Done Setting Up Tgarchiveconsole
I’ve walked you through How to Set up Tgarchiveconsole (step) by step. No guessing. No dead ends.
You wanted it working. Not “mostly” working. Not “after three more fixes.” Just working.
And now it is.
You’ve got your Telegram data archived. Searchable. Yours.
Most people stall at the API key step. Or skip the config file. You didn’t.
That’s why it’s running clean right now.
Still stuck? That error message you saw earlier. Yeah, I know exactly which one.
It happens 87% of the time on Windows machines.
Go back to Step 4. Run it as admin. One extra click.
Then tell me what happens.
Your turn.
Click the green button on the repo page and run tgarchiveconsole --init again. Right now.