# How to Install a Telegram Theme, and What to Do If It Fails **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](https://usemira.pro/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](https://core.telegram.org/themes)). If the author changes the theme, it updates for all its users ([Telegram blog, 2019](https://telegram.org/blog/scheduled-reminders-themes)). - **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](https://desktop.telegram.org/). Telegram for macOS comes from [macos.telegram.org](https://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. 1. **Open the link.** Tap the `t.me/addtheme/…` link. Telegram opens a theme preview. 2. **Have a file? Send it to yourself.** In the Files app, tap Share, choose Telegram and send the file to Saved Messages. 3. **Tap the file in the chat.** Telegram shows the theme preview. 4. **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. 1. **Open the link.** Tap the `t.me/addtheme/…` link. Telegram opens **Theme Preview**. 2. **Have a file? Put it in a chat.** Send the `.attheme` file to Saved Messages. 3. **Tap the file.** Telegram opens **Theme Preview**. The file menu also has **Apply theme file**. 4. **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. 1. **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**. 2. **Check the preview.** The **Theme Preview** window shows your chats in the new colors. 3. **Click Apply this theme.** Telegram Desktop switches the colors and asks **Keep this theme?** 4. **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. 1. **Open the link.** Click the `t.me/addtheme/…` link. Telegram opens **Theme Preview**. 2. **Have a file? Send it to yourself.** Drag the `.palette` file into Saved Messages and send it. 3. **Click the file.** Telegram for macOS shows the theme preview. 4. **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](https://telegram.org/blog/android-streaming)). - **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](https://usemira.pro/blog/telegram-themes) | Theme links, one tap to install | A quick, ready look | | [Theme generator](https://usemira.pro/tools/theme-generator) | Files for iOS, Android, Desktop and macOS from six colors | Your own colors | | [Telegram's theme editor](https://core.telegram.org/themes) | 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](https://telegram.org/blog/android-themes)) | 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](https://t.me/usemirabot?startapp=blog_themeinstall_inline_en) ## 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](https://telegram.org/blog/posts-in-stories-and-more)). 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](https://core.telegram.org/api/themes)). 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](https://usemira.pro/tools/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](https://usemira.pro/tools/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](https://t.me/usemirabot?startapp=blog_themeinstall_final_en)