Usage
Using TweakInject
What each page does, how to install and configure tweaks, and how to recover when a tweak causes a problem.
Installing a tweak
Tweaks are distributed in three formats.
| Format | Description |
|---|---|
.deb | A package containing a tweak along with its name, version and dependencies. The usual distribution format. |
.bundle | A single tweak, containing its code and the filter describing which processes it applies to. |
.dylib | A tweak supplied as a plain library, accompanied by a separate filter file. |
Open Installed Tweaks and drag the file onto the panel at the top of the page, or select Browse. TweakInject reads the tweak's filter from the file and registers it. Anything installed from the store appears on this page as well.
Disabling a tweak leaves it installed but stops it loading. This applies to apps started afterwards; one already running keeps whatever it loaded at launch. Quit and reopen the affected app, or use Restart UI for components such as the Dock and Finder.
Configuring a tweak
Tweaks that have settings can be configured from within TweakInject. Select the tweak in Installed Tweaks to open its settings.
Those same settings also appear in System Settings under a Tweaks section, but only when the PreferenceLoaderX tweak is installed — it is what adds that section. It is available in the store, and tweaks that need it list it as a dependency, so it is usually installed alongside them.
Changes take effect immediately in apps that are already running. Nothing needs restarting unless the tweak says otherwise.
The store
TI Store lists tweaks that can be installed in one step, with any dependencies resolved automatically. Each entry shows a description, artwork and the architectures it was built for.
Store listings are cryptographically signed. The Signed indicator at the top of the page means the catalogue matches what was published, and a listing that fails that check blocks installs rather than merely warning about them. Every package also carries a checksum, and one that does not match is refused.
No account is required to browse or install. Signing in is for publishing a tweak — nothing else needs one.
Third-party repositories
Repositories lists the sources the store draws from. Select Add and enter a repository's address to include it; its tweaks then appear in the store alongside the rest.
Turning injection off
Injection can be suspended from the Injection page. This stops tweaks loading into anything started afterwards while leaving everything installed — useful for running an app unmodified without uninstalling your setup. The status strip in the lower-left corner of the window always shows the current state.
Safe Mode
Safe Mode stops every tweak loading, without uninstalling any of them. It exists for the case where a tweak prevents the desktop working normally.
It engages by itself when it is needed. If a tweak causes the Dock, Finder, Spotlight, the window server or the wallpaper components to crash, Safe Mode is activated automatically and the next session starts with all tweaks stood down. You do not have to do anything for this to happen, and you do not need a working desktop for it to work.
You can also engage it deliberately with Engage Safe Mode in the utilities on the Injection page. While Safe Mode is active, the Injection page shows a Safe Mode indicator, and an item appears in the menu bar offering Exit Safe Mode — so you can leave Safe Mode even if TweakInject itself is not reachable.
To return to normal, disable the tweak you suspect in Installed Tweaks, then select Exit Safe Mode. Leaving Safe Mode restarts userspace so that everything comes back with tweaks loaded.
Restarting userspace
Some changes apply only to processes started afterwards, and a few of those — the Dock, Finder, the window server — cannot be quit. Userspace Reboot, in the utilities on the Injection page, restarts every process without restarting the machine. It ends your session in the same way as signing out, so save your work first.
Restart UI is the lighter option, restarting the Dock, Finder and related components only.
Diagnostics
Process Manager lists every running process and what has been loaded into each, and lets you exempt one from injection. Use it when a single app disagrees with a tweak that is otherwise fine.
Logs records which tweaks loaded into which processes and what failed. It is the first place to check when a tweak is installed and enabled but appears to do nothing.
Publishing your own tweaks
Sign in with GitHub and Developer Center appears in the sidebar, listing the tweaks you have published and the submissions you have sent. A submission carries its files with it — there is nothing to host yourself — and you can withdraw one that has not been reviewed yet.
The account is only used to say who you are. TweakInject asks for no repository access and cannot see your code. Documentation covers submitting and updating a tweak in full.
Settings
Appearance, including the colour theme, along with diagnostics and maintenance actions such as clearing cached store artwork.
Send Feedback is at the bottom of the page. It goes straight to the maintainers and needs no account — sign in first only if you would like to be able to get a reply.