TGArchiveConsole Upgrade: A Safe Step-by-Step Guide for Telegram Archives
A tgarchiveconsole upgrade should take five minutes. For most people it takes an afternoon, because the guides online describe different tools under the same name. One page treats it as a test-log archiver. Another calls it a retro game library. A third describes a desktop app with a “Run Upgrade” button. None of them tell you which one you have.
This guide covers the version most people searching this phrase actually use: the Python-based Telegram archiver published as tg-archive. It pulls messages from a Telegram group into a local SQLite database and builds a static, searchable website from them. If that matches your setup, everything below applies. If it doesn’t, the first section will help you work that out before you run a single command.
The commands here follow the project’s documented workflow as I know it. Check the README for your installed version before running anything against an archive you care about, because options and requirements change between releases.
First, Confirm What You Are Upgrading
Searching for this tool returns pages that contradict each other. Running the wrong upgrade command either does nothing or installs unrelated software. tgarchiveconsole tips from thegamearchives
The Three Things the Name Can Mean
| What the name refers to | What it does | Upgrade route |
|---|---|---|
| tg-archive (Python Telegram archiver) | Syncs a Telegram group into SQLite and builds a static site | pip install --upgrade tg-archive |
| A fork or wrapper called tgarchiveconsole | Varies by repository | git pull, then reinstall |
| Unrelated tools sharing the name (game archives, test-log tools) | Completely different software | That vendor’s own documentation |
A Quick Identification Checklist

You are almost certainly using the Telegram archiver if your project folder contains these:
- A
config.yamlfile withapi_id,api_hash, and agroupsetting - A
data.sqlitedatabase file - A
session.sessionfile created after you logged in to Telegram - A
template.htmlfile and astaticfolder for the generated site - A working
tg-archive --synccommand
If your folder looks nothing like this, stop here. Some pages in the search results tell readers to run npm run sync or click a button in a console. Those instructions belong to different software and will not work on a Python archiver.
Back Up Before Any TGArchiveConsole Upgrade
Most upgrade horror stories come from people who touched their data folder without a copy. The software itself is replaceable. Your archive is not.
Here is the reason this matters more than usual. Telegram lets people delete messages. If someone deleted a message after your last sync, your local database may be the only place it still exists. Losing data.sqlite means losing that history permanently.
What to Protect
| File or folder | What it holds | Cost of losing it |
|---|---|---|
data.sqlite | Every message you have synced | Messages deleted on Telegram are gone for good |
config.yaml | API credentials, group ID, build settings | Annoying, but you can re-enter it |
session.session | Your logged-in Telegram session | You must log in again with a code |
| Media folder | Downloaded images, files, stickers | Re-download, which can be slow |
template.html and static/ | Your site layout and styling | Lose any customization you made |
| Built site output | Generated HTML pages | Rebuildable from the database |
Backup Commands
Stop any running sync or scheduled job first, so nothing writes to the database mid-copy.
On Linux or macOS:
cp -r ~/mysite ~/mysite-backup-$(date +%F)
On Windows PowerShell:
Copy-Item -Recurse .\mysite .\mysite-backup
Treat session.session like a password. Anyone who holds that file can act as your Telegram account, so keep your backup somewhere private and never upload it to a public repository or paste it into a forum.
Check Your Current Version and Environment
Before upgrading, write down what you have now. You will need it for troubleshooting and for rolling back.
Find the Installed Version
python -m pip show tg-archive
Note the Version: line and the Location: line. The location tells you which Python environment owns the install, which becomes important in a moment.
Check Your Python Version
python --version
On some systems the command is python3. Newer releases of any Python tool can raise the minimum Python version, and older interpreters will refuse the install or silently stay on an old release. Read the release notes for the version you are heading to.
Make Sure You Are in the Right Environment
The most common complaint in these guides is the same one: “I upgraded, but it still shows the old version.” The cause is almost always two Python installations on one machine. Plain pip can belong to a different interpreter than the one running your archiver.
The fix is to always call pip through the interpreter:
python -m pip install --upgrade tg-archive
That guarantees the package lands in the same environment as the python command you just ran. If you use a virtual environment, activate it first.
Three Ways to Do a TGArchiveConsole Upgrade
Pick the method that matches how you installed the tool originally. Mixing methods is where version confusion starts.
Method 1: Upgrade With pip
This suits anyone who installed from PyPI, which is most people.
python -m pip install --upgrade pip
python -m pip install --upgrade tg-archive
python -m pip show tg-archive
The last command confirms the new version number. If it matches the release you wanted, the install worked.
Method 2: Upgrade From a Git Clone
Use this if you cloned the repository to track the latest code or to carry local changes.
cd path/to/tg-archive
git status
git pull
python -m pip install --upgrade .
Run git status first. If you have uncommitted changes, git pull may refuse or create merge conflicts. If the repository includes a requirements.txt, you can also run python -m pip install -r requirements.txt --upgrade to refresh dependencies.
Method 3: Pin a Specific Release

If the latest version breaks something, or you want a predictable setup, install an exact version:
python -m pip install tg-archive==<version>
Replace <version> with a release number from PyPI or the repository’s releases page. This is also the safest choice for servers running scheduled syncs.
How the Methods Compare
| Method | Best for | Main advantage | Main risk |
|---|---|---|---|
| pip upgrade | Most users | One command, easy to verify | Wrong environment gives a false “success” |
| Git pull | Contributors and tinkerers | Latest code, easy to diff changes | Merge conflicts, unreleased bugs |
| Pinned version | Servers, scheduled jobs | Predictable and reproducible | You must remember to bump it manually |
After the Upgrade: Verify Before You Trust It
Don’t run your first post-upgrade sync against your only copy of the database. Test on the backup.
- Confirm the version with
python -m pip show tg-archive. - Move into the backup folder you created earlier.
- Run a sync from there:
tg-archive --sync. - Build the site:
tg-archive --build. - Preview it locally:
tg-archive --serve. - Open the site and check that dates, media, avatars, and replies still render.
For a stronger check, count the stored messages before and after. With the sqlite3 command-line tool installed:
sqlite3 data.sqlite "SELECT COUNT(*) FROM messages;"
If you get an error about the table name, run .tables inside sqlite3 to see what your schema calls it. The count after the sync should be equal to or higher than before. A lower count means something went wrong and you should restore from backup.
Check Whether Your Template Needs Changes
New releases can change the variables a template expects. If you customized template.html, a build might fail or render blank sections after upgrading. To compare, generate a fresh site in a temporary folder:
tg-archive --new --path=temp-site
Then diff the default template.html in that folder against yours, and copy across any new variables or blocks. This takes ten minutes and prevents most post-upgrade rendering bugs.
Troubleshooting a Failed Upgrade
Most of the errors people hit after a tgarchiveconsole upgrade fall into a few categories. This table covers the common ones.
| Symptom | Likely cause | Fix |
|---|---|---|
| Version unchanged after upgrading | pip belongs to a different Python | Use python -m pip, check Location: in pip show |
ModuleNotFoundError or Telethon import errors | Dependency conflict or broken environment | Create a fresh virtual environment and reinstall |
| Asked to log in again | session.session moved, renamed, or invalidated | Keep it in the site folder; log in again with the code Telegram sends |
FloodWaitError | Too many requests in a short time | Wait the number of seconds shown; do not loop retries |
| Build fails or pages render blank | Template out of date | Diff your template against a fresh --new project |
| Command not found | Scripts folder is not on your PATH | Add Python’s Scripts folder (Windows) or ~/.local/bin (Linux) to PATH |
| Permission denied during install | Installing into system Python | Use a virtual environment or add --user |
Building a Clean Virtual Environment
When dependency errors pile up, a clean environment is faster than debugging. On Linux or macOS:
python3 -m venv tgenv
source tgenv/bin/activate
python -m pip install --upgrade pip
python -m pip install tg-archive
On Windows PowerShell, activate with .\tgenv\Scripts\Activate.ps1. Then copy your site folder in and run a sync. Your data stays in the project folder, so nothing is lost by rebuilding the environment.
Roll Back If Something Breaks
A rollback plan is the part most guides skip, and it is the part you need when an upgrade goes wrong.
- Stop any running sync or scheduled job.
- Reinstall the previous version using the number you wrote down earlier:
python -m pip install tg-archive==<old-version>. - If the new version modified your database before you noticed a problem, restore
data.sqlitefrom your backup. Downgrading the software does not necessarily undo changes made to the data. - Restore your
config.yamlandtemplate.htmlfrom the backup if you edited them. - Run
tg-archive --buildand confirm the site renders as before.
Notice that the whole process depends on the version number and the backup copy from earlier. Without those two things, a rollback becomes guesswork.
Automating Without Autopiloting Your Upgrades
Many guides recommend scripting the entire tgarchiveconsole upgrade. That is a bad idea for an archive you depend on. An unattended upgrade can install a release with breaking changes at 2 a.m., and you find out when the site is blank.
A better split:
- Automate the sync. A daily cron job is reasonable.
- Pin the version. Keep the exact release in a requirements file.
- Upgrade by hand. Do it monthly, or when release notes mention a fix for something you hit.
A cron entry using a virtual environment looks like this:
0 2 * * * cd /home/user/mysite && /home/user/tgenv/bin/tg-archive --sync && /home/user/tgenv/bin/tg-archive --build
Pointing directly at the virtual environment’s executable avoids the wrong-Python problem entirely. Windows users can get the same result with Task Scheduler and a full path to the executable.
Avoid Fake Downloads and Unverified Installers
Several low-quality pages tell readers to “visit the official website” and run an installer, without ever linking to one. For a command-line Python tool, that advice should make you suspicious. There is no reason for a pip-installed archiver to ship as a random .exe.
Follow these rules for any tgarchiveconsole upgrade:
- Install from PyPI or from the project’s GitHub repository, and nowhere else.
- Check the repository owner, commit history, and release dates before cloning.
- Never paste your
api_hash, phone number, or session file into a website. - Get your API credentials only from my.telegram.org, which is Telegram’s own developer portal.
- Read the source of a script before giving it your Telegram login if you did not write it.
Alternatives If the Upgrade Keeps Failing
Sometimes the right answer is a different tool, especially if you only need a one-off copy of a chat.
| Option | Best for | Trade-off |
|---|---|---|
| Telegram Desktop export | A one-time snapshot in HTML or JSON | No continuous sync, no searchable site |
| Telethon script | Developers who want custom output | You maintain the code yourself |
| MadelineProto (PHP) | PHP developers | Heavier and less command-line friendly |
None of these replace a working archive with years of synced history, so fix the upgrade first if you can.
The TGArchiveConsole Upgrade Checklist

Use this as a quick reference each time:
- Identify the tool: Telegram archiver, fork, or something unrelated.
- Stop running syncs and scheduled jobs.
- Back up
data.sqlite,config.yaml,session.session, media, and templates. - Record the current version with
pip show. - Confirm your Python version and active environment.
- Upgrade using
python -m pip, or pull from Git if you cloned. - Verify the version number changed.
- Test a sync and build on a copy of the archive.
- Diff your template against a fresh default if you customized it.
- Compare message counts, then switch back to your live folder.
Frequently Asked Questions
Is a tgarchiveconsole upgrade safe for my existing archive?
Yes, provided you back up data.sqlite, config.yaml, and session.session first. The upgrade replaces the program, not your data.
How often should I upgrade?
Only when release notes fix something you have hit, or when Telegram changes break your sync. There is no benefit to upgrading on a fixed schedule.
Will I lose messages during an upgrade?
Not from the upgrade itself. Messages are lost when the database file is deleted or overwritten, which is why the backup comes first.
Why does pip still show the old version?
You almost certainly have more than one Python installation. Run python -m pip instead of pip, and check the Location: line in pip show.
Do I need to log in to Telegram again after upgrading?
Usually not, as long as session.session stays in your project folder. Moving or deleting it forces a fresh login.
Does the upgrade work the same on Windows?
Yes, the commands are the same. Use PowerShell, call python -m pip, and make sure Python’s Scripts folder is on your PATH.
Is there an official tgarchiveconsole installer?
I could not verify one. Stick to PyPI and the project’s GitHub repository rather than installers from unfamiliar sites.
Final Thoughts
The hard part of a tgarchiveconsole upgrade is not the command. It is knowing which tool you have, protecting the database that holds your history, and confirming the upgrade landed in the right Python environment. Do those three things and the pip command itself is the easy part.
Keep a note of your working version, pin it on any server, and test changes on a copy. That routine turns every future upgrade into a five-minute job.