Opacity (Alpha Channel) fails to render on Windows 11 LTSC with latest Windows Terminal

[CoWave-Fall]

Have you checked closed issues? (https://github.com/Textualize/textual/issues?q=is%3Aissue+is%3Aclosed)

• Yes.

Have you checked against the most recent version of Textual? (https://pypi.org/search/?q=textual)

• Textual, version 5.3.0.

Consider discussions!

Issues are for actionable items only.
If Textual crashes or behaves differently from the docs, then submit an issue.
If you want to know how to do something, or you have a suggestion for a new feature, then open a discussion (https://github.com/Textualize/textual/discussions/).

For realtime help, join our discord server (https://discord.gg/Enf6Z3qhVr)

The bug

Bug description

The Textual application background does not render with transparency on Windows 11 LTSC 24H2, even when the Windows Terminal itself is transparent and correctly supports 24-bit True Color. Setting background: transparent or background: rgba(...) results in an opaque background.

Environment

• OS: Windows 11 LTSC, Version 24H2
• Terminal: Windows Terminal, Version 11.22.12111.0
• Textual: 5.3.0
• Python: 3.13

To Reproduce

1. Ensure Windows Terminal has transparency enabled (e.g., Acrylic effect).
2. Run the following minimal Textual application:

   from textual.app import App, ComposeResult
   from textual.widgets import Static
   
   class TransparentApp(App):
       CSS = """
       Screen {
           background: transparent; /* Also fails with rgba(0, 0, 0, 0.5) */
           align: center middle;
       }
       Static {
           width: auto;
           border: heavy green;
       }
       """
       def compose(self) -> ComposeResult:
           yield Static("This background should be transparent.")
   
   if __name__ == "__main__":
       app = TransparentApp()
       app.run()

Expected behaviour

The application background should be transparent, showing the desktop or other windows behind the terminal. If using rgba, the background should be semi-transparent.

Actual behaviour

The application background is fully opaque (typically black), completely covering the terminal's transparent effect.

Diagnostics and additional context

• The terminal does support 24-bit True Color. The following test script produces a smooth color gradient as expected:

    import os
    # ANSI True Color Escape Sequences
    # CSI (Control Sequence Introducer) is '\033[' or '\x1b['
    # SGR (Select Graphic Rendition) for 24-bit color is '38;2;<R>;<G>;<B>' for foreground
    # and '48;2;<R>;<G>;<B>' for background.
  
    def true_color_gradient():
        for i in range(256):
            # Foreground color for a simple gradient
            r = i
            g = 255 - i
            b = 0
            # Background color (darker for contrast)
            bg_r = int(i * 0.5)
            bg_g = int((255 - i) * 0.5)
            bg_b = 0
        
            # Use a space character to show the background color
            print(f"\x1b[38;2;{r};{g};{b};48;2;{bg_r};{bg_g};{bg_b}m ", end="")
        print("\x1b[0m") # Reset all attributes
  
    if __name__ == "__main__":
        print("--- True Color Gradient Test ---")
        print("If you see a smooth color gradient below, True Color is supported.")
        true_color_gradient()
        print("--- End Test ---")
        print("\n")
        print("Checking COLORTERM environment variable:")
        print(f"COLORTERM: {os.environ.get('COLORTERM')}")
        print(f"TERM: {os.environ.get('TERM')}")

• Attempts to use a full-screen Container with a transparent background also failed.

• An attempt to force a legacy driver (textual.drivers.windows_driver.WindowsDriver) resulted in ModuleNotFoundError, as this driver no longer exists in recent versions.

This strongly suggests an issue with the default Textual driver's handling of the alpha channel on this specific Windows environment.

Thanks a lot.

Textual Diagnostics

Versions

Name	Value
Textual	5.3.0
Rich	14.1.0

Python

Name	Value
Version	3.13.6
Implementation	CPython
Compiler	MSC v.1944 64 bit (AMD64)
Executable	D:\Project\blivechat-tui.venv\Scripts\python.exe

Operating System

Name	Value
System	Windows
Release	11
Version	10.0.26100

Terminal

Name	Value
Terminal Application	Windows Terminal
TERM	Not set
COLORTERM	Not set
FORCE_COLOR	Not set
NO_COLOR	Not set

Rich Console options

Name	Value
size	width=140, height=30
legacy_windows	False
min_width	1
max_width	140
is_terminal	True
encoding	utf-8
max_height	30
justify	None
overflow	None
no_wrap	False
highlight	None
markup	None
height	None

[github-actions]

We found the following entries in the FAQ which you may find helpful:

• Why doesn't Textual look good on macOS?
• Does Textual support images?
• How do I center a widget in a screen?

Feel free to close this issue if you found an answer in the FAQ. Otherwise, please give us a little time to review.

This project is developed and maintained by Will McGugan. Consider sponsoring Will's work on this project (and others).

This is an automated reply, generated by FAQtory

[TomJGooding]

Looks like the bot missed the mark here...

• How can I set a translucent app background?

[CoWave-Fall]

Thank you, @TomJGooding. Your pointer to the documentation was correct.

The App(ansi_color=True) setting has resolved the issue.

After reading the relevant FAQ sections, I now understand the design rationale behind prioritizing True Color over ANSI-based transparency. I acknowledge this is an intentional design trade-off.

I apologize for the oversight in not reading the documentation more carefully beforehand.

Closing this issue as resolved. Thank you for your assistance.

[github-actions]

I hope I solved your issue!

Consider sponsoring my work to continue to maintain and develop Textual.

• Will McGugan