Introduction

iTerm2 has a new drawing engine that uses Metal 2. For many users, this will significantly improve performance.

Benefits

• 60 frame per second rendering. Buttery smooth!
• Increased throughput (e.g., when you cat a giant file, it'll finish sooner.)
• Most users will see improved latency (time between pressing a key and seeing it drawn.)

Availability

The Metal renderer is available in version 3.2.0.

The new renderer is not available for some configurations:

1. Transparent windows are not supported. They must be opaque. This is because subpixel anti-aliasing becomes too complex.
2. You must disable ligatures for both ASCII and non-ASCII fonts in Prefs > Profiles > Text. Ligatures are very hard to support in a GPU-based renderer.
3. If you have adjusted Prefs > Advanced > Height of top and bottom margins in terminal panes to be less than 2, the Metal renderer will not be used.
4. Vertical spacing for your fonts (as configured in the font panel) must not be set to less than 100% (the default).

It is also temporarily disabled under certain conditions:

1. When another view, such as the find bar, is drawn overtop the terminal.
2. When your device is not plugged into a charger. This is controlled by Prefs > General > Advanced GPU Settings > Disable GPU renderer when disconnected from power.

Most of these restrictions will be relaxed when macOS Mojave comes out.

Support

Support me at https://www.patreon.com/gnachman 😁

If you have issues, please see below:

Troubleshooting

You can disable it in Prefs > General > GPU Rendering.

To see if it's working, or find out why it isn't enabled, select Help > GPU Renderer Availability.

How to report performance issues

1. Create a new issue at https://iterm2.com/bugs, if needed
2. Make sure this is on: Prefs > Advanced > Log stats about text drawing performance to console.
3. Create a new window
4. Scroll through a big file or whatever it is that's slow
5. Select iTerm2 > Copy Performance Stats
6. Paste into the issue report (cmd-V)

Note that recorded stats are erased when iTerm2 becomes active, so the only drawing that's timed is between when iTerm2 became active and when you copied the stats out.

How to report drawing problems

1. Make the session that's drawing wrong is active (i.e., it would receive keyboard input)
2. Select iTerm2 > Capture GPU Frame (it will be enabled if Metal is in use)
3. Wait a few seconds
4. File a bug at https://iterm2.com/bugs and attach /tmp/iTerm2-frame-capture.zip.

Please let me know if you have any problems.