Prevent iTerm 2 from opening extra windows by navigating to Preferences under the iTerm menu, selecting the General tab, and locating the Window Restoration section. Uncheck or disable the option labeled Restore previous sessions on startup. This action stops the application from automatically recreating your previous terminal layout every time you launch it, ensuring a clean slate each session.
Understanding Window Restoration Behavior
Many users find that iTerm 2 behaves differently than other macOS applications when it comes to closing and reopening. While most apps simply close their main window, terminal emulators often attempt to preserve the state of multiple panes, tabs, and splits. This feature is designed for productivity, allowing developers to resume complex workflows without reconfiguring their environment. However, this convenience can become a nuisance if you prefer starting with a single, empty window every time you open the terminal. The core issue lies in how iTerm 2 handles session persistence. By default, the application saves the state of all open windows, including those created via hotkeys or manual interactions. When you quit the application, it writes this state to disk. Upon relaunch, it reads this file and attempts to reconstruct the exact environment you left behind. If you have inadvertently closed only the hotkey window but left another pane open, or if the restoration policy is set too broadly, iTerm 2 will spawn additional windows to match the saved configuration. This results in the unexpected appearance of non-hotkey windows upon startup. To address this, we must look at the specific settings governing this behavior. The solution does not involve complex scripting or external tools but rather a straightforward adjustment within the application's native preferences. By modifying the restoration policy, you gain full control over whether iTerm 2 should remember your previous session or start fresh. This approach aligns with best practices for maintaining a predictable development environment, especially when using hotkey windows for quick tasks while keeping the main workspace clear. For more information on managing terminal configurations, see iTerm2: Running Commands Every New Pane, which explores further customization options for your shell environment.Locating the General Preferences Tab
The first step in resolving this issue is accessing the correct settings panel. Open iTerm 2 and click oniTerm in the top-left menu bar of your screen. From the dropdown menu, select Preferences... (or press Cmd + ,). This opens the main preferences window, which contains several tabs for different aspects of the application's behavior.
Navigate to the General tab. This section houses fundamental settings related to the application's lifecycle, including updates, notifications, and window management. Within the General tab, look for the subsection titled Window Restoration. This area specifically controls how iTerm 2 handles the saving and loading of window states. It is crucial to interact with this specific section, as other tabs like Keys or Profiles do not contain the necessary toggles for session persistence.
If you do not see the Window Restoration section immediately, ensure you are on the correct tab. Some older versions or custom builds might organize these settings slightly differently, but the standard distribution places them here. Once located, you will see a checkbox or toggle switch that dictates whether previous sessions are restored.
Disabling Session Restoration
In the Window Restoration section, you will find an option labeled Restore previous sessions on startup. To prevent non-hotkey windows from opening automatically, uncheck this box. This setting is the primary driver for the behavior described in the problem statement. When enabled, iTerm 2 saves the state of all open windows, including splits and tabs, and restores them exactly as they were when the application was last closed. By disabling this option, you instruct iTerm 2 to start with a default configuration every time. This means that even if you had ten panes open during your last session, launching the application again will result in a single, empty window. This is particularly useful for users who frequently use the hotkey window feature for quick commands and do not want their main desktop cluttered with residual terminal instances. After unchecking the box, close the Preferences window. The changes take effect immediately for new sessions. You may need to quit iTerm 2 completely and restart it to verify that the behavior has changed. If you still experience issues, ensure that no other plugins or scripts are overriding this setting. For example, some users employ shell profiles that auto-launch additional windows, which would bypass iTerm 2's internal restoration logic. Another common cause for unexpected windows is the use of third-party utilities that manage window placement or auto-open terminals based on system events. If disabling the restoration option does not solve the problem, consider reviewing any active daemons or background processes that might be triggering terminal launches. Additionally, check your shell configuration files (.zshrc or .bash_profile) for any commands that might spawn new instances.
For tips on cleaning up your terminal environment, refer to How to delete all the color presets in iTerm2?, which offers guidance on streamlining your visual settings.
Verifying Hotkey Window Settings
While disabling general restoration solves the majority of cases, it is worth verifying your hotkey window configuration. Navigate to the Keys tab in Preferences and locate the Hotkey Window section. Ensure that the hotkey is assigned correctly and that the window type is set to Global Hotkey. Sometimes, conflicts between global hotkeys and local shortcuts can cause unexpected window behaviors. If you rely heavily on the hotkey window, you might want to keep it separate from the restoration policy. Unfortunately, iTerm 2 does not offer a granular setting to restore only the hotkey window while ignoring others. Therefore, the most reliable method remains disabling restoration entirely. If you need to preserve certain sessions, consider using iTerm 2's built-in bookmarking feature or saving specific profiles instead of relying on automatic restoration.Frequently Asked Questions
Will disabling restoration delete my current open windows?
No, disabling this setting only affects future startups. Your currently open windows will remain intact until you choose to close them. When you quit iTerm 2 after making this change, it will not save the state of those windows, so they will not reappear next time you launch the app.
Can I restore only specific windows while ignoring others?
The native preferences do not support selective restoration based on window type. You must either restore all previous sessions or none at all. If you need fine-grained control, you may need to use AppleScript or third-party automation tools to manage window states manually.
Why do non-hotkey windows still appear occasionally?
If you have disabled restoration but still see extra windows, check for shell scripts or aliases that might be spawning new instances. Also, ensure that no other applications are interacting with iTerm 2 via command line arguments that force window creation.
Does this fix apply to iTerm 3 beta versions?
Yes, the Window Restoration setting in the General tab remains consistent across stable and beta releases of iTerm 2 and iTerm 3. The location and naming of the option have not changed in recent updates.
How do I reset my preferences if I make a mistake?
You can reset all preferences by holding down the Option key while clicking the Reset button in the bottom-left corner of the Preferences window. This will revert all settings to their default values, including the restoration policy.