Installation

The installation starts in macOS and continues in Fedora:

1. In macOS Recovery, disable Secure Boot and allow booting from external media.
2. In macOS, create a separate partition for Fedora.
3. Boot macOS and run the KAIT2EN installer.
4. Choose a supported Fedora edition and an empty USB drive.
5. The installer downloads and verifies the official Fedora image.
6. It collects the Apple Wi-Fi firmware from your Mac and, where required, the PCIe Bluetooth firmware.
7. It writes the unchanged Fedora image to the USB drive, then adds separate KAIT2EN boot files for keyboard, trackpad, firmware, and installer support.
8. Boot the USB drive and install Fedora. After the first login, the guided KAIT2EN setup installs the remaining drivers and system integration.
9. After another reboot, you can enjoy KAIT2EN on top of vanilla Fedora.

The installer currently supports Fedora Workstation, Fedora KDE Desktop and Fedora COSMIC Spin. We strongly recommend installing Workstation (Gnome) because that is what we devs use ourselves. KDE and Cosmic are generally more problematic. We can't help you with that because we don't use it.

Before you start

You need:

• a T2 Mac with macOS still installed
• an empty USB drive
• an internet connection in macOS

Back up important data before changing partitions or boot settings.

Keep macOS installed. It is the clean source for Apple firmware and can recover T2/bridgeOS hardware states.

Disable Apple Secure Boot#

• Shut down the Mac.
• Turn it on and immediately hold Command-R until macOS Recovery starts.
• Select a macOS administrator account and enter its password when prompted.
• From the menu bar, open Utilities > Startup Security Utility.
• Select the macOS system disk if the utility asks for one.
• Set the following options:

Secure Boot: No Security

Allowed Boot Media: Allow booting from external or removable media

• Close Startup Security Utility and restart into macOS.

Apple Secure Boot cannot boot standard Fedora while it is enabled. The installer checks the current setting and warns when it cannot confirm that Secure Boot is disabled.

Create space for Fedora#

Open Disk Utility in macOS. Select the internal macOS disk or container, choose Partition, and add a real exFAT partition for Fedora. Do not add an APFS volume. Fedora will reformat this partition during installation; exFAT only makes it easy to identify.

Choose the size carefully because resizing the partitions later is not a small maintenance task. Keep at least 50 GB for macOS so there is enough space for updates, firmware work, and recovery tasks. Give the remaining space you want to use for Linux to the new partition.

Do not delete the EFI partition or macOS.

Create the Fedora USB drive

Boot macOS and connect the empty USB drive. Open Terminal and run:

curl -fsSL https://github.com/kaiT2en/KaiT2en-Fedora/releases/latest/download/install-kait2en-fedora.sh | bash

Choose the Fedora desktop and USB drive. The script downloads and verifies the official Fedora image, finds the Apple Wi-Fi firmware used by this Mac and asks for an exact confirmation before erasing the USB drive.

The official Fedora image itself is not modified. After writing the verified vanilla image, the script adds KAIT2EN boot files only to the USB drive's EFI partition. Separate initramfs overlays provide the temporary input drivers and installer integration at boot; Fedora's live system and installation payload remain unchanged.

Be exact when selecting the drive. All data on it will be destroyed.

Install Fedora

Shut down or reboot the Mac. Hold Option during startup and select the orange EFI Boot entry for the Fedora USB drive. The KAIT2EN Fedora entry starts automatically.

Keyboard, trackpad, and Wi-Fi should work in the live system and installer. The live system installs the Apple Wi-Fi firmware from the USB drive for itself, so you can connect to a network before or instead of installing Fedora.

Macs whose Bluetooth controller sits on PCIe (BCM4377) also get their Apple Bluetooth firmware in the live system, so a Bluetooth keyboard or mouse can be paired before installing. Every other T2 Mac drives Bluetooth over UART and needs no separate firmware file.

Install Fedora normally. Use custom partitioning and select the Linux partition you created in macOS. Do not erase the whole disk or macOS. When reinstalling, format an existing Linux /boot partition so old kernels do not fill it.

After installation finishes, remove the USB drive and boot the installed Fedora system.

If the live system does not start#

The boot menu offers a few troubleshooting entries that are only needed when the normal boot does not work. Try them in this order and stop at the first one that works:

1. Troubleshooting: KaiT2en with boot messages shows the console instead of the logo. Photograph the last lines for a bug report.
2. Troubleshooting: KaiT2en with the dedicated GPU disabled keeps amdgpu out of the boot and leaves the Intel GPU fully accelerated.
3. Troubleshooting: KaiT2en with basic graphics adds nomodeset. Rendering is done in software and feels slow, but it can run the installation.
4. Troubleshooting: KaiT2en with basic graphics and conservative PCIe is the last resort and also covers a power off coming from PCIe or Thunderbolt.

All of them keep the KAIT2EN input drivers. If entry 2 or 3 was needed, make the fix permanent afterwards as described in Configure GPUs.

If hardware is missing in the live system#

KAIT2EN supports the known T2 configurations, but Apple shipped several controller and firmware variants. If keyboard, trackpad, Wi-Fi, or PCIe Bluetooth support is missing, collect diagnostics before continuing with the installation.

The individual helpers can be run manually to see the Wi-Fi or Bluetooth setup result directly:

sudo /run/kait2en/kait2en-live-wifi
sudo /run/kait2en/kait2en-live-bluetooth

For a complete diagnostic archive, run:

sudo /run/kait2en/kait2en-live-diagnostics --rerun

This reruns the firmware setup while recording what happened. The archive lands on a second USB drive when one is mounted, otherwise in /tmp; the path is printed at the end. It contains host names, MAC addresses, and the names of nearby wireless networks, so inspect it before attaching it to a bug report.

Finish the KAIT2EN installation

Sign in to Fedora and connect to Wi-Fi. A terminal opens automatically and starts the KAIT2EN installer in two phases. Do not close this window and follow the prompts.

The first phase updates Fedora and prepares the new kernel. Reboot when asked. After signing in again, the second phase opens automatically and runs the regular KAIT2EN installer. Reboot once more after it completes successfully.

If the terminal does not appear, open one and run this command without sudo:

kait2en-install

The installer asks for administrator access when it is needed. It can also be started again at any later time to update KAIT2EN.

Audio DSP

This page explains the audio DSP support that KAIT2EN installs automatically. It is not an installation guide. Supported Macs receive the matching profile during the regular KAIT2EN installation; unsupported models continue to use the native T2 audio devices.

DSP in general#

The T2 audio driver exposes the physical speaker channels, but it does not contain the model-specific processing Apple applies before those channels reach the internal speakers. KAIT2EN provides that processing as a PipeWire filter graph.

Depending on the model, the graph

• distributes stereo audio across the physical woofer and tweeter channels
• applies model-specific FIR filters to correct the frequency response;
• adds virtual-bass processing where appropriate and controls peaks before they reach the internal speakers.

On supported Macs, the resulting output appears as DSP Speakers device. The unprocessed Apple Internal Speakers device remains available for comparison and diagnostics. Headphones do not pass through the speaker DSP graph.

Supported models#

The installer identifies the model from DMI and only deploys a graph when an explicit matching profile exists. KAIT2EN does not reuse a profile on an unlisted model.

Automatic selection#

The WirePlumber software-DSP integration gives the DSP sink a higher session priority than the underlying speaker sink. WirePlumber should therefore select the DSP output automatically when the profile is first created.

Profile origins and support#

The KAIT2EN DSP implementation originated from lemmyg's t2-apple-audio-dsp, but it is no longer a direct copy of that project. Its graphs have been substantially reworked, adapted to the KAIT2EN UCM profiles and WirePlumber software-DSP integration, and extended with model-specific measurements and FIRs from Asahi Linux or our own.

Problems with these profiles must be reported to the KAIT2EN issue tracker. Do not report KAIT2EN DSP behavior to lemmyg's project: its current routing, filter graphs and UCM integration are maintained here.

The exact source and license information for each profile is recorded in the DSP module and alongside imported FIR files.

Check the active output#

The sound settings should show the model-specific DSP output on a supported Mac. PipeWire can also list it directly:

wpctl status

The active sink is marked with an asterisk. If the DSP device is missing after the regular installation and a reboot, include the model identifier and this output in a KAIT2EN issue:

cat /sys/class/dmi/id/product_name
wpctl status
journalctl --user -b -u wireplumber -u pipewire -u pipewire-pulse

Configure GPUs

If a Mac has a dGPU, it will use it for boot and it will also use it as primary display adapter by default. An iMac is no exception in that aspect, but it is not able to switch between internal and dedicated GPU because the display lines from iGPU to display are missing. So on iMacs, the iGPU is only used for offloading. Thus, if you are an iMac user, this guide is not for you. Same for Mac Pro users, since Mac Pros have no iGPU. This guide is only for Macbook Pro users.

MacBookPro15,1: enable hybrid graphics#

KaiT2en installs T2 Hybrid GPU Control on the MacBookPro15,1. Open it from the application menu and enable Hybrid graphics.

Hybrid graphics makes the integrated GPU the display GPU. Applications can still use the AMD GPU through PRIME offload. The kernel wakes it automatically for accelerated work and returns it to D3cold when it becomes idle. This keeps the dGPU available without paying its idle power cost.

The installer builds the required AMDGPU and HDA modules for the current Fedora kernel. The app reports whether the required runtime-PM support is active.

These two modules are not managed by DKMS. After Fedora installs a new kernel, first reboot into that kernel and then rebuild its hybrid-graphics modules:

cd /usr/local/src/KaiT2en-Fedora
sudo ./scripts/fedora/install-gpu-runtime-pm.sh
sudo reboot

Running the script before booting the new kernel only rebuilds the modules for the old, currently running kernel. Until the rebuild and second reboot are complete, hybrid runtime PM is not available on the new kernel.

The discrete-GPU boot option remains available as a recovery setting. Rebooting is always a separate action so changing the stored boot GPU does not restart the system unexpectedly.

Other Intel/AMD MacBook Pro models continue to use T2 GPU Control. Hybrid runtime PM is not enabled on those models because their dGPU power-on path is not yet reliable.

Hardware video decoding

Fedora's GPU drivers do not expose hardware decoding for codecs such as H.264 and H.265. This affects both AMD GPUs and Intel iGPUs. Browsers and media players can therefore fall back to CPU decoding even though the GPU contains a supported video decoder.

T2 Macs do not provide AV1 hardware decoding. YouTube should use H.264 or a hardware-supported VP9 profile to avoid unnecessary CPU load.

Install the VA-API drivers#

Run the installer from the KAIT2EN repository:

sudo bash ./scripts/fedora/install-hardware-video-decoding.sh

The script enables RPM Fusion, installs the appropriate VA-API drivers for every detected Intel and AMD GPU, and checks each render node. Review the final output: H.264 and VP9 decoding and encoding are reported as available or missing for each GPU.

No general system upgrade is performed. Browser configuration is still required as described below.

Brave and YouTube#

Open Brave's system settings and enable Use graphics acceleration when available, then restart Brave.

YouTube normally chooses between H.264, VP9 and AV1 based on the capabilities reported by the browser. T2 Macs cannot decode AV1 in hardware. To force YouTube to request H.264 in Brave, install h264ify from the Chrome Web Store. This does not interfere with Brave Shields or its ad blocking.

H.264 streams on YouTube are commonly limited to 1080p. Disable the extension when a higher resolution is more important than lower CPU use.

Start a YouTube video, right-click it and open Stats for nerds. The codec field identifies the selected stream:

• avc1 is H.264.
• vp09 is VP9.
• av01 is AV1.

For the forced H.264 configuration, the field must start with avc1.

Open brave://gpu and check that Video Decode reports hardware acceleration. For the active playback session, brave://media-internals provides the more useful per-stream decoder details.

Firefox and YouTube#

In Firefox settings, leave hardware acceleration enabled. Open about:config, set the following preference to false, and restart Firefox:

media.av1.enabled

This disables AV1 but still allows YouTube to select VP9. To force H.264, install enhanced-h264ify from Mozilla Add-ons and block VP9 and AV1 while leaving H.264 enabled.

Use YouTube's Stats for nerds as described above. Firefox also reports its decoder support under about:support in the codec and media sections.

Test outside the browser#

MPV can confirm that VA-API works independently of browser configuration:

mpv --no-config \
    --hwdec=vaapi-copy \
    --hwdec-codecs=all \
    --vaapi-device=/dev/dri/renderD128 \
    --term-playing-msg='Hardware decoder: ${hwdec-current}' \
    /path/to/video.mp4

Replace the render node and video path as required. A hardware-decoded stream reports vaapi-copy instead of no.

Updating

KAIT2EN is meant to disappear. It's part of the concept. It serves the purpose of upstreaming code fixes. Every module and fix that gets upstreamed will disappear from the repo. Until we are left with a few T2 specific apps and other things that can't be upstreamed. Maybe it will survive as a collection of helpful apps for T2 Macs.

As long as this isn't the case, we need to update the Fedora kernel and our modules and apps. The question how to do that has kept us a bit busy. We could go COPR and offer .rpm. But the project is yet too small to fund itself.

Updating KAIT2EN#

Open a terminal and run:

kait2en-install

This updates the KAIT2EN Git checkout and runs the regular project installer. Review its output and reboot after it completes successfully.

Updating Fedora#

You just update Fedora like everyone else. DKMS will notice and recompile our modules against the latest kernel. It's always worth visiting the KAIT2EN community on Discord or Matrix to make sure you won't run into issues like kernel regressions.

So you messed up?#

You can mess up DKMS when upgrading the kernel. For example when interrupting DKMS while the new Kernel is booting. Then you are left with half broken KAIT2EN modules. To repair this, just boot into an older kernel and clean up the new.

#replace the kernel version 7.1.3-201.fc44.x86_64 with your own
sudo dracut --force /boot/initramfs-7.1.3-201.fc44.x86_64.img 7.1.3-201.fc44.x86_64 
sudo kernel-install add 7.1.3-201.fc44.x86_64 /lib/modules/7.1.3-201.fc44.x86_64/vmlinuz
sudo grubby --set-default /boot/vmlinuz-7.1.3-201.fc44.x86_64

Murphy's law: We WILL mess up!#

We are humans. We will mess up at some point. We recommend not to update when you don't have an external keyboard/mouse around. Like when you are travelling. But you should always be able to use GRUB to boot into an older kernel anyways. But be warned that when we mess up, you could loose VHCI devices or WiFi. And remember we are not paid. We will waste your time and we don't accept complaints.

Installed files

KAIT2EN keeps Fedora's vanilla kernel and installs T2 hardware support as a separate layer. The changes we are doing to your system are documented here to provide transparency to users and devs.

Project checkout and updater#

The guided installer creates a clean checkout of the main branch at:

/usr/local/src/KaiT2en-Fedora

kait2en-install fast-forwards this checkout and runs scripts/fedora/install.sh. It refuses to overwrite local changes or use a checkout with an unexpected Git remote. Its persistent files are:

/usr/local/bin/kait2en-install
/var/lib/kait2en-installer/state
~/.local/state/kait2en/install.log

Kernel modules#

The installer copies each module source to /usr/src/<name>-<version>/, registers it with DKMS and builds it for the running Fedora kernel. DKMS keeps its build state below /var/lib/dkms/ and rebuilds the modules for later kernel updates. modinfo -n <module> prints the installed kernel object path.

The installer also writes /etc/kernel/install.d/39-kait2en-dkms-cleanup.install. The hook removes stale DKMS build state before a kernel installation is retried.

On the MacBookPro15,1, the app installer also builds the AMDGPU and Intel HDA modules with the hybrid runtime-PM patches and installs them for the running kernel at:

/usr/lib/modules/<kernel>/updates/kait2en-gpu-runtime-pm/amdgpu.ko.xz
/usr/lib/modules/<kernel>/updates/kait2en-gpu-runtime-pm/snd-hda-intel.ko.xz

The corresponding modprobe and dracut configuration is installed as /usr/lib/modprobe.d/kait2en-gpu-runtime-pm.conf and /etc/dracut.conf.d/90-kait2en-gpu-runtime-pm.conf.

Unlike the T2 modules above, these patched AMDGPU and HDA modules are not built by DKMS. After a Fedora kernel update, boot the new kernel before rebuilding them for its exact release:

cd /usr/local/src/KaiT2en-Fedora
sudo ./scripts/fedora/install-gpu-runtime-pm.sh
sudo reboot

The script installs the modules for the running kernel and rebuilds that kernel's initramfs.

Kernel arguments#

install-kernel-args.sh updates every installed kernel entry with grubby --update-kernel=ALL. Inspect the effective arguments with:

grubby --info=DEFAULT

KAIT2EN adds these arguments to every installed kernel through grubby:

intel_iommu=on
iommu=pt
pm_async=off
brcmfmac.p2pon=0
pcie_aspm=force
pcie_aspm.policy=powersave
pcie_ports=native
pci=noaer
mem_sleep_default=deep
initcall_blacklist=cmos_init,magicmouse_driver_init
module_blacklist=acpi_tad,applesmc,macsmc,hid_apple,hid_appletb_bl,hid_appletb_kbd,hid_magicmouse,appletbdrm,apple_bce,apple_mfi_fastcharge,apple_gmux

On MacBook Pro models where PCI discovery finds an AMD display device, the installer additionally enables GuC submission and HuC firmware loading for the Intel GPU:

i915.enable_guc=2

KAIT2EN does not install a custom kernel or a separate GRUB configuration file.

Audio configuration#

The ALSA UCM profiles define the T2 speaker, microphone and headset paths:

/usr/share/alsa/ucm2/AppleT2/HiFi-x2.conf
/usr/share/alsa/ucm2/AppleT2/HiFi-x4.conf
/usr/share/alsa/ucm2/AppleT2/HiFi-x6.conf
/usr/share/alsa/ucm2/conf.d/AppleT2x2/AppleT2x2.conf
/usr/share/alsa/ucm2/conf.d/AppleT2x4/AppleT2x4.conf
/usr/share/alsa/ucm2/conf.d/AppleT2x6/AppleT2x6.conf

The installer deploys model-specific FIR filters and a generated WirePlumber rule on these models: MacBookAir8,1, MacBookAir8,2, MacBookAir9,1, MacBookPro15,1, MacBookPro15,4, MacBookPro16,1, MacBookPro16,2, MacBookPro16,3 and MacBookPro16,4.

/usr/share/kait2en/audio-dsp/<profile>/
/etc/wireplumber/wireplumber.conf.d/51-kait2en-t2-dsp.conf

Every other model exits the DSP step without creating these files. See Audio DSP for the supported-model table, audio behavior and diagnostics.

System configuration and services#

kait2en-suspend.service is enabled on every installation. Before suspend, it checks for a Broadcom PCI device with vendor ID 0x14e4 and device ID 0x5f69, 0x5f71, 0x5f72 or 0x5fa0. If one is present, it unloads brcmfmac_wcc, brcmfmac and hci_bcm4377 in that order. After resume it loads brcmfmac and brcmfmac_wcc, waits five seconds, then loads hci_bcm4377.

If the controller is absent, the service logs that the fix is not needed and does not unload a module. State files for modules successfully unloaded by the helper exist only until resume below /run/kait2en-suspend/.

The installer checks the running kernel log for two known Apple ACPI firmware errors. It only deploys an override when the error is present and the generated table passes validation with iasl:

/usr/local/lib/firmware/acpi/*.aml
/usr/local/lib/firmware/acpi/.kait2en-*.sha256
/etc/dracut.conf.d/t2-acpi-fix.conf
/var/backups/t2-acpi-fix/<timestamp>/

The backup contains every managed file that existed before deployment and a manifest. KAIT2EN only replaces or removes an ACPI table when its ownership marker contains the table's current SHA-256 checksum. Existing unmarked tables and modified managed tables are left unchanged and reported as conflicts.

Apple firmware from the installer USB drive#

The guided installer copies Apple's own firmware for this Mac from the USB drive into the installed system, renamed to the file names the Linux drivers ask for:

/usr/lib/firmware/brcm/brcmfmac<chip>-pcie.apple,<board>*

Macs with the BCM4377 PCIe Bluetooth controller (14e4:5fa0) additionally get the two Bluetooth blobs. Every other T2 Mac drives Bluetooth over UART and gets nothing here:

/usr/lib/firmware/brcm/brcmbt<chip><stepping>-apple,<board>[-<vendor>].bin
/usr/lib/firmware/brcm/brcmbt<chip><stepping>-apple,<board>[-<vendor>].ptb

The exact names are taken from what the driver asked for in the kernel log. The outcome of the Bluetooth step is recorded in the installed system at:

/var/log/kait2en/bluetooth-firmware.log

Desktop applications#

t2-fan-control, t2-smc-control, and t2-power-explorer are built from the checkout and installed system-wide under /usr/local. The MacBookPro15,1 gets t2-hybrid-gpu-control; other MacBook Pro models with Intel and AMD display devices get t2-dgpu-control.

T2 SMC Control creates /etc/t2-smc-control/config.txt only after a charge limit is saved. Its system service restores that value at boot. T2 Fan Control's service starts immediately and persists fan curves across boot and resume. T2 Hybrid GPU Control does not install system services. T2 GPU Control enables its units only when the corresponding options are applied in the app. Both privileged helpers validate the GPU layout and accept only the fixed operations exposed by their UI.

react-drm is installed for the desktop user only when the DMI product name is one of MacBookPro15,1, MacBookPro15,2, MacBookPro15,3, MacBookPro15,4, MacBookPro16,1, MacBookPro16,2, MacBookPro16,3 or MacBookPro16,4:

~/react-drm/
~/.config/systemd/user/react-drm.service
/etc/udev/rules.d/99-react-drm.rules

The installer adds that user to the video and input groups. When the active desktop reported by the user's systemd environment contains gnome, it also installs Window Monitor Pro below ~/.local/share/gnome-shell/extensions/ for application-aware controls. Every other DMI product name exits this step before installing react-drm dependencies or files.