[iTerm2 Series 2] Installation and Basic Setup

Install iTerm2 and apply the base settings

This guide installs iTerm2 and applies a few settings that make daily terminal work more comfortable. We assume you already finished the Homebrew setup, because the rest of this series also uses Homebrew-based installs.

What we'll cover

• Install iTerm2 via Homebrew
• Configure fonts and themes
• Adjust the core behaviors that make daily use easier

Before you start

You need:

• A Mac
• Internet access
• Admin permissions
• Homebrew already installed

Time required: roughly 10-15 minutes

Compatibility: Recent iTerm2 releases run on both Intel and Apple Silicon Macs. If you are on an older macOS version, check the current iTerm2 requirements before you install.

Before you run the install command, verify that Homebrew is ready:

brew --version

If you see a version number, continue. If not, install Homebrew first at brew.sh.

Step 1: Install iTerm2 with Homebrew

Run this command in your current terminal:

brew install --cask iterm2

If the command finishes without an error, iTerm2 is installed.

Why use Homebrew?

• Updates are a single command: brew upgrade --cask iterm2.
• Removal stays clean with brew uninstall --cask iterm2.
• When you migrate to a new Mac, you can re-run the same command.

Verify the install

Use a direct check instead of scanning the whole cask list:

brew list --cask iterm2

If Homebrew prints iterm2, the install succeeded.

Step 2: First launch

Open iTerm2 once so you can confirm it starts normally before changing settings.

You can also double-click iTerm2 in the Applications folder.

Most recent iTerm2 builds are signed and notarized, so they usually open without a security warning. If your Mac does show a warning, follow the on-screen prompt to allow the app.

Step 3: Preferences basics

Open Preferences:

Command + , (comma)

Check the default profile

Preferences → Profiles → Default

💡 What is a profile? It is a saved set of terminal settings such as font, colors, and startup behavior. You can keep separate profiles such as "development" or "server maintenance."

Change the font

Move to the text settings for the default profile:

Preferences → Profiles → Default → Text tab

Optional: install a developer font

After the install, open Font Book and search for Fira Code if you want to confirm macOS registered it. Then return to iTerm2, switch Font to Fira Code, and start with 14pt.

Fourteen points is a practical starting size on many Mac displays. If your screen is small, go down a little. If you still squint, go up a little.

Font size shortcuts (after setting the font):

Command + +  → Increase font size
Command + -  → Decrease font size
Command + 0  → Reset to default size

⚠️ If something looks off: When the font gets too small or too big, press Command + 0 to reset.

Step 4: Theme (color) setup

Many developers prefer a dark theme for long terminal sessions, but this is still a personal choice. Start with a built-in preset first.

Apply a built-in theme (recommended path)

Preferences → Profiles → Default → Colors tab

Color Presets dropdown:

• Choose Dark for a simple dark background.
• Or pick Solarized Dark, a common developer favorite that is already built in.

Import a custom theme file (optional)

The built-in preset is enough for most readers. Only use this path if you want to try extra color schemes from the mbadolato/iTerm2-Color-Schemes repository.

Download the repository, unzip it, and open the schemes/ folder inside the downloaded project.

Import into iTerm2:

Preferences → Profiles → Default → Colors tab
↓
"Color Presets" dropdown → "Import..."
↓
Select "Solarized Dark.itermcolors" from the folder you downloaded
↓
"Color Presets" → choose "Solarized Dark"

💡 Why Solarized?

• Distinct ANSI colors
• Good readability in many developer tools
• A familiar preset used in many terminal tutorials

Optional transparency/blur

If you like a softer background, test small values first:

Preferences → Profiles → Default → Window tab

Suggested starting values:

Transparency: around 10-20%
Blur: 10-20

⚠️ If the background becomes unreadable: Set Transparency back to 0%.

Step 5: Core behavior settings

Startup behavior

This is the most useful quality-of-life setting in the post because it reduces repeated cd commands.

Preferences → Profiles → Default → General tab
↓
Working Directory section

Recommended checkbox:

☑ Reuse previous session's directory

What this changes in practice:

• Suppose you are in /Users/username/Documents/project/src.
• You open a new tab in the current iTerm2 session.
• The new tab starts in the same directory, so you keep your context.

This setting is mainly about tabs and sessions you open while iTerm2 is already running. If you want iTerm2 to restore windows and tabs after a full restart, check the separate restore behavior in general preferences.

Remember window size

Use this as a starting point, not a strict rule:

Preferences → Profiles → Default → Window tab
↓
Settings for New Windows

Suggested values:

Columns: 100-120
Rows: 30-40

💡 Why: Too small and output wraps too early; too large and the window takes over your screen. On a smaller MacBook display, start near the lower end of the range.

Step 6: Key shortcuts to memorize

These are the shortcuts you will reach for most often once the setup is done.

Shortcut	Action
Command + T	New tab
Command + N	New window
Command + W	Close tab or pane
Command + D	Horizontal split
Command + Shift + D	Vertical split
Command + [	Move to previous pane
Command + ]	Move to next pane
Command + ;	Autocomplete
Command + F	Search
Command + +	Increase font size
Command + -	Decrease font size

How these settings help in real work

These changes matter because they remove small interruptions:

• Reuse previous directory: open a new tab and stay inside the project you were already using.
• Readable font size: zoom in quickly during pair programming or presentations, then reset with Command + 0.
• Theme preset: make long command-line sessions easier to scan.
• Window size range: reduce awkward wrapping in logs, Git output, and editor-like terminal tools.

Confirm everything works

Use these quick checks so you confirm the result instead of only trusting the clicks you made.

Quick checks:

• Run brew list --cask iterm2 and confirm Homebrew prints iterm2.

• Open iTerm2 and confirm the window launches normally.

• Check that the font looks different after switching to Fira Code or your preferred font.

• Check that the background color changed if you applied a preset.

• brew install --cask iterm2 completed successfully

• iTerm2 launches without errors

• Font changed to a readable size

• Theme preset applied

• New tabs reuse the previous directory

• Command + T opens a new tab

Behavior test:

1. Launch iTerm2.
2. Run cd Documents.
3. Press Command + T to open a new tab.
4. Run pwd in the new tab.
5. Confirm the new tab starts inside Documents.

Common mistakes

Issue 1: iTerm2 will not open

Symptom: macOS says the app is damaged or the app fails to start.

Fix:

brew uninstall --cask iterm2
brew install --cask iterm2

Issue 2: Korean text is corrupted

Fix:

Preferences → Profiles → Default → Text tab
↓
☑ Treat ambiguous-width characters as double width

This is mainly useful when CJK text such as Korean, Japanese, or Chinese renders with broken spacing.

Issue 3: Fonts look blurry

Fix:

Preferences → Profiles → Default → Text tab
↓
☑ Anti-aliased
☑ Draw bold text in bold font

Anti-aliasing smooths the edges of letters, so this setting often improves readability.

Issue 4: Preferences will not save

Fix:

Preferences → General → Preferences
↓
If "Load preferences from a custom folder or URL" is checked, uncheck it.

Issue 5: Can't find the downloaded files

Fix:

open ~/Downloads

Success criteria

When you can say you're done:

• iTerm2 is installed and opens normally
• Default profile reviewed
• Font changed (optional but recommended)
• A theme preset was applied
• New tabs keep the previous directory
• Key shortcuts reviewed

Recommended next steps:

1. Use iTerm2 as your default terminal for real work.
2. Practice Command + D splits.
3. Practice Command + ; autocomplete.

Next post

After the install and base setup, we will dive into split panes, search, and advanced shortcuts.

iTerm2 Series 3: Split panes, search, shortcuts shows how to put iTerm2's flagship features into daily use.