How to Install a Telegram Theme, and What to Do If It Fails

Q: Which file type do I need for Telegram Desktop?

Telegram Desktop needs a .tdesktop-theme file. This is true on Windows, Linux and Mac. Telegram for macOS is a different app. It needs a .palette file.

Author: Mira TeamPublished: October 11, 2026Updated: October 18, 2026

themes
telegram
how-to

TL;DR

A theme link (t.me/addtheme/…) is the easiest install. One link works in every Telegram app the theme supports.
A theme file works in one app only. iPhone reads .tgios-theme, Android .attheme, Telegram Desktop .tdesktop-theme, Telegram for macOS .palette.
A theme that does not apply usually has one of three causes: a file for another app, Auto-Night Mode or your own wallpaper.
A theme changes only your own Telegram. Your subscribers never see it.

To install a Telegram theme, open its t.me/addtheme/… link in Telegram and tap Apply. Have a file instead? Send it to Saved Messages, tap it and apply it in the preview. The file must match your app.

If the theme does not show, find your symptom in the table below.

A Telegram theme is a set of colors for your own Telegram app. It can also carry a background. We make Mira (usemira.pro), a Telegram bot that finds posts for channels.

We also made the 18 free themes and the theme generator below. So we are not neutral.

We checked the facts in this article on 2026-10-11. We installed a .tgios-theme file from our generator on an iPhone (iOS and Telegram versions not recorded). The link steps and the other apps follow Telegram's documentation and app texts.

If you find an error, write to us via the contact page.

Link or file: which one do you have?

A link installs in one tap, and it is the better choice. A file needs a few more steps and works in one app only.

A theme link looks like t.me/addtheme/name. Telegram calls these cloud themes. Telegram says one link sets the theme on every platform it supports (Telegram theme docs). If the author changes the theme, it updates for all its users (Telegram blog, 2019).
A theme file is a file you download, for example from our generator. Each app reads its own file type. A file for Android will not install on an iPhone.

Our advice: if you can get a link, use the link. Take a file when there is no link or when you made the theme yourself.

Which file does your device need?

Each Telegram app reads one theme file type. Find your app in this table first.

Your device	Telegram app	Theme file	How to open it
iPhone or iPad	Telegram for iOS	`.tgios-theme`	Send to Saved Messages, tap the file
Android phone or tablet	Telegram for Android	`.attheme`	Send to Saved Messages, tap the file
Windows or Linux	Telegram Desktop	`.tdesktop-theme`	Open the file, or Settings → Chat Settings → Choose from file
Mac	Telegram Desktop	`.tdesktop-theme`	The same as on Windows
Mac	Telegram for macOS	`.palette`	Send to Saved Messages, click the file
Browser	Telegram Web	none	We found no theme install in the web version

The Mac has two different Telegram apps. Telegram Desktop comes from desktop.telegram.org. Telegram for macOS comes from macos.telegram.org or the Mac App Store.

To check which one you have, open Settings. Telegram for macOS has an Appearance section, like the iPhone app. Telegram Desktop has Chat Settings with a Choose from file button.

How do I install a theme on iPhone or iPad?

Open the theme link on your iPhone. With a file, send it to Saved Messages and tap it. We installed a generator file this way; the link step follows Telegram's documentation.

Open the link. Tap the t.me/addtheme/… link. Telegram opens a theme preview.
Have a file? Send it to yourself. In the Files app, tap Share, choose Telegram and send the file to Saved Messages.
Tap the file in the chat. Telegram shows the theme preview.
Apply the theme. Tap the apply button at the bottom of the preview.

How do I install a theme on Android?

Tap the theme link, or tap the .attheme file in a Telegram chat. Then tap Apply in the preview. These steps follow Telegram's documentation and app code; we did not check them on a device.

Open the link. Tap the t.me/addtheme/… link. Telegram opens Theme Preview.
Have a file? Put it in a chat. Send the .attheme file to Saved Messages.
Tap the file. Telegram opens Theme Preview. The file menu also has Apply theme file.
Tap Apply. Telegram confirms that the color theme changed. You can switch back in Chat Settings.

How do I install a theme in Telegram Desktop?

Open the .tdesktop-theme file in Telegram Desktop, click Apply this theme, then click Keep changes. The steps are the same on Windows, Linux and Mac. They follow Telegram's documentation and app code; we did not check them on a device.

Open the theme. Click the theme link, or click the .tdesktop-theme file in any chat. You can also use Settings → Chat Settings → Choose from file.
Check the preview. The Theme Preview window shows your chats in the new colors.
Click Apply this theme. Telegram Desktop switches the colors and asks Keep this theme?
Click Keep changes. Do it within about 15 seconds. If you wait, Telegram Desktop goes back to the old theme.

How do I install a theme in Telegram for macOS?

Open the theme link in Telegram for macOS. With a file, send the .palette file to Saved Messages and click it. These steps follow Telegram's documentation and app code; we did not check them on a device.

Open the link. Click the t.me/addtheme/… link. Telegram opens Theme Preview.
Have a file? Send it to yourself. Drag the .palette file into Saved Messages and send it.
Click the file. Telegram for macOS shows the theme preview.
Apply the theme. Click the apply button. The theme appears in Settings → Appearance.

The theme did not apply: find your symptom

Find the message or symptom you see, then use the fix in the same row. The quoted messages are the texts of Telegram's own apps.

What you see	What it means	What to do
"Sorry, this color theme doesn't support your device yet." (iPhone, Android)	The theme behind the link has no version for your app	Ask the author for your app's file, or make a theme in our generator
"Sorry, this theme doesn't seem to exist for macOS."	The same, in Telegram for macOS	The same as above
"Incompatible with macOS, click to edit" under a theme in Appearance	That cloud theme has no macOS version	Pick another theme, or click it and edit it into a macOS version
"Incorrect theme file" (Android) or "Invalid data in this theme file." (Desktop)	The file is for another app, or it is damaged	Check the file type in the table above. Download the file again
"Keep this theme? Reverting to the old theme in 15 seconds."	Telegram Desktop waits for your answer	Click Keep changes before the countdown ends
"You can't apply a new theme while editing the color palette."	The theme editor is open in Telegram Desktop	Close the editor, then open the theme again
The `.tdesktop-theme` file does nothing on a Mac	You use Telegram for macOS	Use a `.palette` file, or install Telegram Desktop
The file opens in a text editor or a file viewer	The file was opened outside Telegram	Send it to Saved Messages and open it there
The bubbles changed, but the background did not	Your own wallpaper stays on top of the theme color	Pick a plain or default background in Chat Background settings
The theme switches back in the evening	Auto-Night Mode changes the theme	See "Why does my theme change at night?" below
One chat looks different from the rest	That chat has its own chat theme or wallpaper	Open that chat and remove its theme or wallpaper
The theme is on your phone, not on your computer	A file installs on one device only	Open the same theme link on the computer, or download the file for the computer's app (see the table above)

Our advice: start with the file type. A file for the wrong app causes most of these rows. After that, check Auto-Night Mode, then your wallpaper.

Why does my theme change at night?

Auto-Night Mode switches Telegram to a night theme. By the app code, it can follow a schedule, the light level or your system. It then shows the theme you chose as the preferred night theme (Telegram blog, 2018).

Your theme is dark: in Auto-Night Mode, select it as the Preferred night theme.
Your theme is light: set Auto-Night Mode to Disabled, or accept the switch at night.

On Android, open Settings → Chat Settings → Auto-Night Mode. On iPhone, open Settings → Appearance → Auto-Night Theme. Telegram for macOS has Auto-Night Mode in its Appearance settings.

In Telegram Desktop, turn off Auto-night mode in Settings → Chat Settings. We took all these paths from the app code and did not check them on a device.

How do I go back to the default theme?

Pick one of the built-in themes in your app's theme settings. Your installed theme stays in the list, so you can switch back later.

iPhone and iPad: Settings → Appearance → pick a built-in theme under Color Theme.
Android: Settings → Chat Settings → pick a built-in theme under Color theme.
Telegram Desktop: Settings → Chat Settings → under Themes, pick Day, Classic, Tinted or Night.
Telegram for macOS: Settings → Appearance → Reset to Defaults, or pick a built-in theme.

Where can I get a theme?

There are four good places to get a theme. Pick by what you want to do with it.

Source	What you get	Best for
18 free Telegram themes	Theme links, one tap to install	A quick, ready look
Theme generator	Files for iOS, Android, Desktop and macOS from six colors	Your own colors
Telegram's theme editor	A cloud theme with a public link	Sharing one link for every app
Desktop Themes and Android Themes channels	Themes made by Telegram users	Browsing many styles (Telegram blog, 2017)

Our advice: start with a ready theme link. Use the generator when you want your own colors. Use Telegram's editor when you want to share one link with other people.

Run a Telegram channel? Mira finds posts for it from your sources, and you review them in its Mini App.

Open in Telegram

Frequently asked questions

Why is my Telegram theme not working?

The most common reason is a file for another app. Each Telegram app reads its own file type.

Other reasons are Auto-Night Mode and your own chat wallpaper. In Telegram Desktop, check that you clicked Keep changes. The symptom table above has a fix for each message.

Which file type do I need for Telegram Desktop?

Telegram Desktop needs a .tdesktop-theme file. This is true on Windows, Linux and Mac.

Telegram for macOS is a different app. It needs a .palette file.

Can my subscribers see my theme?

No. A theme changes only your own Telegram app.

Subscribers see your channel in their own theme. A boosted channel can set a wallpaper that everyone sees (Telegram blog, 2023). That is a separate channel setting.

Do Telegram themes sync between devices?

Cloud themes from a link are saved to your account (Telegram API docs).

We did not check that they appear on every device by themselves, so open the same link on each device. A theme file stays on the device where you open it.

How do I remove a Telegram theme?

First switch to a built-in theme in your theme settings. Then open the menu of the theme you want to delete.

Choose Remove on iPhone or Delete theme on Android. We took these names from the app code and did not check them on a device.

Are Telegram themes safe to install?

A theme holds colors and sometimes a background image. Telegram shows a preview before you apply it.

We still advise themes from sources you know. These are Telegram's channels, known authors or your own files. You can always go back to the default theme.

Can I make my own Telegram theme?

Yes. Our theme generator turns six colors into files for iPhone, Android, Desktop and Mac.

You need Telegram only to install the file. Telegram's own editor needs a Telegram login.

Make your own theme next

A ready theme is fast, but your own colors fit your style. Pick six colors in the theme generator and download the file for your app.

Do you run a channel? Mira finds and drafts its posts, and you approve them in its Mini App.

Open in Telegram