Two kinds of software hold a Telegram login. The desktop app keeps it in a folder, and libraries keep it in a single file. People cross between them for ordinary reasons. An account a script has been driving needs a person to read its chats, or needs the chat export that only Telegram Desktop offers. An account opened in Desktop has a chore ahead that nobody wants to click through, such as walking out of every group in one pass. In both cases the useful question is what exactly gets moved.
What is inside a tdata folder and a session file?
A single key, wrapped four different ways.
When a client signs in, it and Telegram agree on an authorization key, and from then on that key is the login. On disk a session is the key plus the number of the data centre that issued it. Library documentation uses Telegram and session as a fixed pairing for that reason: the account, and one stored login to it. Everything else in the file is bookkeeping.
That is all telegram tdata is at its core, too. The desktop app writes a folder named tdata into its working directory, and inside it a key file encrypted with a local key. The local key is random. It is wrapped in turn by a key made from the app's local passcode, which is empty unless somebody set one. The same folder is covered from the user's side in how a portable build keeps tdata beside the exe. A library file is plainer. Telethon's session is an SQLite database, and Pyrogram's is another with different columns.
| Container | Read by | Holds besides the key | Has no place for | Locked by |
|---|---|---|---|---|
| tdata folder | Telegram Desktop | User ID, data centre, local settings, cache | api_id and device strings; the app supplies its own | Local passcode, if one was set |
| Telethon .session | Tools built on Telethon | Data centre number, server address, port, entity cache | User ID, api_id | Nothing |
| Pyrogram .session | Tools built on Pyrogram | Data centre number, api_id, user ID, a bot flag | Server address | Nothing |
| String session | The library that produced it | The same values as that library's file, as one line of text | Caches | Nothing |
| JSON beside a session | Tools that share the convention | api_id and hash, device, app version, language, phone, two-step password | The key itself | Nothing |
The two library rows come from each project's storage source and the tdata row from Telegram Desktop's, all read in October 2026. The JSON row is a convention, as explained further down.
Bots are the exception. A bot signs in with a token from BotFather and Telegram Desktop cannot open one, so a library session that belongs to a bot has no tdata to become. It is one more way to tell whether a product runs on a bot or on a signed-in account. The files in this article belong to user accounts, the kind that really sends what gets sold as a DM bot, while a true bot stays on the invite-link side of bringing members in.
Telegram session to tdata: the key moves, the login stays
Nothing new is created on Telegram's side.
A converter opens the session file, reads the data centre number and the key, and writes both into a fresh tdata folder with an empty passcode. One value is missing. tdata records the account's numeric user ID next to the key, and a Telethon session has no column for it. opentele, the open-source library most converters are built on, connects once and asks Telegram whose session it is when the ID is absent. A Pyrogram file already has it, and so does a JSON that lists it. Only then can the whole job run offline.
Two different operations go by the name telegram session to tdata, and a telegram tdata converter rarely says which one it runs. opentele calls them UseCurrentSession and CreateNewSession. The first is the copy described above. In the second, the existing session approves a brand-new login through Telegram's QR flow, so the account ends up with a second authorization that has its own key. A new login needs the network and the old session alive, and it adds an entry to the account's list of devices.
One session in two files, and the error that ends both
After a copy, the original session file and the tdata made from it are the same session.
By default Telegram allows one live connection per key. Its error documentation describes AUTH_KEY_DUPLICATED as what a data centre returns when it detects "an authorized session is sending requests in parallel from two separate TCP connections", and adds that by then "the session was already invalidated by the server". The account must sign in again from nothing. So a converted copy is not a backup that can run beside the original. Stop the script before Telegram Desktop opens the folder, and close Desktop before the script starts again.
The network changes with the client as well. A proxy line in a JSON is a note for the tool that reads it, and Desktop ignores it. Once the folder is open there, the account connects through whatever Desktop's own SOCKS5 or MTProto proxy screen says.
Does telegram tdata to session work the same way in reverse?
Mostly, with a lock in the way.
Going from tdata, the converter has to decrypt the key file first, and that needs the local passcode whenever one was set. With no passcode the folder opens for anyone who holds it. With one, a telegram tdata to-session run stops at a decryption error until the right passcode is typed. People mix this up with the two-step verification password, which lives on Telegram's servers and plays no part in reading a folder.
A folder can also hold more than one login. Desktop keeps every account added to an install in the same tdata, which is covered under how many accounts one app can stay signed in to, so a single folder may come out as several session files.
Then there is the choice of output. A telegram session converter in the narrow sense turns a Telethon file into a Pyrogram one or back, and it is the same small rewrite. Telethon to Pyrogram needs an api_id and the user ID supplied from outside. Pyrogram to Telethon needs the server address filled in for the data centre. A telegram session format converter that lists six formats is doing this with string sessions and JSON pairs added, and it is still moving a single key.
What is a telegram session json file for?
It carries what the key cannot.
Every connection a client opens starts by describing itself. The initConnection method takes an api_id, a device_model, a system_version, an app_version and three language fields. None of them has a column in a Telethon session, so a tool must find them elsewhere each time it connects. The telegram session json is where tools write them down: the app credentials, the device, the app version and the language, next to the phone number, the user ID and the two-step password. No Telegram page defines the file, and field names vary.
The api_id in it matters most. The API terms say "You must obtain your own api_id for your application", covered in why an api_id is tied to one developer number. The page that issues one says accounts logging in through unofficial clients "are automatically put under observation". How Telegram reacts when a session later shows a different api_id or device from the one it signed in with is not written down. Converter authors advise against it, and that is their observation, not policy.
What a telegram session json to tdata run drops
Most of the JSON.
Desktop announces itself with its own built-in identity, and tdata has no slot for another app's credentials or device name. A telegram session json to tdata conversion therefore keeps two things from the file. One is the user ID, which the folder needs. The other is the two-step password, which belongs in a password manager, because Desktop will ask for it before sensitive actions such as handing a channel to a new owner. The phone field is only a label. It signs nothing in, and it has no bearing on who can look the account up by its number. Going back, a JSON has to be written fresh.
Where is the tdata folder on Windows, Linux and macOS?
In the app's working directory, on every system.
The path is built in Telegram Desktop's source as the working directory plus "tdata/", and a -workdir switch on the command line points the app at a different directory. The defaults below are where the folder usually turns up. The rule is documented in code, and no official list of paths exists.
| System | Usual location | Worth knowing |
|---|---|---|
| Windows, installed | %APPDATA%\Telegram Desktop\tdata | Per Windows user |
| Windows, portable | tdata beside Telegram.exe | Moves with the folder |
| Linux | ~/.local/share/TelegramDesktop/tdata | Snap and Flatpak builds keep it inside their own sandbox directory |
| macOS, Telegram Desktop | ~/Library/Application Support/Telegram Desktop/tdata | The native Telegram app from the App Store is a different program with no tdata |
Searches for telegram tdata linux usually come from someone holding a folder made on Windows. It opens. The desktop client is one codebase on all three systems, and the tdata it writes is the same format, so a folder produced by a converter on a Windows PC can be handed to a Linux build with -workdir. The reverse works too.
Is there a telegram session link that signs an account in?
Not one that can be kept.
The nearest thing is the QR login token. The QR login page in Telegram's documentation describes a token "embedded in a tg://login?token=" address, with an expiry it gives as usually 30 seconds, that an app already signed in has to accept. It starts a new login and carries no existing one. The other candidate is a string session, a line of text that some tools label a telegram session link. That one is the key itself, and Telethon's documentation warns that anyone holding the string can log in as the account.
Either file is the account
Whoever copies a tdata folder or a session file can act as that login with no code and no password until it is terminated. A converter that wants files uploaded to a website is asking for the accounts. The remedy sits in the official apps: under Privacy and Security, the Active sessions list ends any login, and one button ends all the others. A fresh login has a waiting period here. The reset method refuses with FRESH_RESET_AUTHORISATION_FORBIDDEN when "less than 24 hours have passed", so a session produced by the new-login kind of conversion cannot cut off the old one on its first day.
Session → TDATA in the panel: a batch of files in, folders out
The module is the copy operation, run over a list.
Accounts sit in the suite as Session + JSON pairs or as TDATA, in one table. The module takes the pairs you select and writes a tdata folder for each on the PC it runs on. Nothing is uploaded. The walkthrough below shows the converter on screen, in both directions.
The reason to run it is usually a person. Some work is easier with eyes on the official app: reading replies, saving somebody as a contact by hand, or clearing out an address book one careful name at a time. Software work stays on the session side, whether that is posting to groups on a schedule or removing what an account has posted.
Telegram session converter software comes in three shapes. A script built on an open-source library is free, handles one account per run and is yours to maintain. A hosted converter needs the files uploaded, which hands over the accounts. Local software does the same rewrite as the script with a batch, a report and a table around it. Underneath, the bytes that move are identical.
What the converter will not do
It will not bring back a session Telegram has terminated, and it cannot read a tdata folder locked with a passcode nobody has. The single-connection rule still holds for its output, so a converted folder and its source file take turns. It changes nothing about how Telegram treats the account. On file formats Telegram's Terms of Service are silent, and they do forbid using the service to "send spam or scam users", whichever container the login sits in. We supply no accounts, sessions, tdata or proxies. A folder that came from somebody else may still exist on their disk, and a converter cannot change that either.