Post

macOS Fresh Install Setup: Complete Developer Tools & Apps Guide

Comprehensive guide for setting up macOS after fresh installation. Install essential developer tools, configure Homebrew, Git, Python, Java, and must-have apps.

Posted Updated
Complete macOS Fresh Install Setup Guide for Developers - Essential Tools and Applications
Complete macOS Fresh Install Setup Guide for Developers - Essential Tools and Applications
By Sagar Nikam
14 min read
macOS Fresh Install Setup: Complete Developer Tools & Apps Guide

Setting up a fresh macOS installation can be overwhelming for developers and power users. This complete macOS setup guide covers essential developer tools, Homebrew installation, and productivity apps to get your Mac development-ready quickly.

Whether you’re a seasoned developer or just starting your coding journey, this comprehensive guide provides step-by-step instructions for configuring the perfect development environment on your new Mac. From package managers to programming languages, we’ll cover everything you need for a productive workflow.

Table of Contents

System Information & Setup

Check macOS Version

Verify your macOS version and system information:

1

sw_vers

1

system_profiler SPSoftwareDataType

1

uname -a

Configure System Names

Customize your computer’s identity for network and terminal display:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Computer Name (User-Friendly Name)
sudo scutil --get ComputerName
sudo scutil --set ComputerName "Your New Computer Name"

# System Hostname (what the Terminal prompt often shows)
sudo scutil --get HostName
sudo scutil --set HostName "your-new-system-hostname"

# Local Hostname (Bonjour Name)
sudo scutil --get LocalHostName
sudo scutil --set LocalHostName "your-new-local-hostname"

# Flush DNS Cache (Optional but Recommended)
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

Package Managers

Homebrew is the most popular package manager for macOS, making it easy to install and manage developer tools.

1

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Why Homebrew? Simplifies software installation, handles dependencies automatically, and keeps packages updated.

Install MacPorts (Alternative)

MacPorts is an alternative package manager (optional if you’re using Homebrew):

1
2
3
4

sudo port selfupdate # update port
port installed # list all installed ports
port outdated # list outdated ports
port upgrade vim # upgrade specific port

Terminal Configuration

Create .zshrc File

Set up your shell configuration file:

1

nano ~/.zshrc

Enable Terminal Colors

Colorize terminal output for better readability:

1
2

echo 'export CLICOLOR=1' >> ~/.zshrc
source ~/.zshrc

Shell Configuration

Change shell if needed (macOS uses Zsh by default):

1
2
3
4
5
6
7
8

# List available shells
cat /etc/shells

# Change to Bash (if needed)
chsh -s /bin/bash

# Change back to Zsh
chsh -s /bin/zsh

Enhance your Zsh experience with themes and plugins:

1
2
3
4
5
6
7
8
9
10

# Install Oh My Zsh
sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# Popular themes to try (edit ~/.zshrc)
# ZSH_THEME="robbyrussell"  # Default
# ZSH_THEME="agnoster"      # Popular choice
# ZSH_THEME="powerlevel10k/powerlevel10k"  # Advanced

# Useful plugins (edit ~/.zshrc)
# plugins=(git brew docker kubectl python)

Development Tools

Install Xcode Command Line Tools

Essential for development and Git:

1

git --version  # This will prompt to install if not present

Install UV (Python Package Manager)

UV is a fast Python package manager for managing multiple Python versions (covered in detail in Python Development section):

1
2
3

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv python install 3.10 3.11 3.12 3.13

Essential Applications

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# Browsers
brew install --cask google-chrome firefox

# Development Tools
brew install --cask visual-studio-code cursor
brew install --cask jetbrains-toolbox eclipse-ide android-studio

# Terminal Tools
brew install --cask iterm2
brew install tmux

# Git GUI Clients
brew install --cask github-desktop

# Communication
brew install --cask slack zoom microsoft-teams
brew install --cask discord whatsapp telegram

# Productivity
brew install --cask dropbox notion
brew install --cask alfred rectangle

# Design Tools
brew install --cask figma

# Databases
brew install --cask dbeaver-community mysql-workbench tableplus

# DevOps
brew install --cask docker lens postman

# Utilities
brew install wget node

# Media Players & Video Tools
brew install --cask vlc
brew install ffmpeg

Manual Downloads (If Homebrew Not Available)

Browsers

Code Editors & IDEs

  • Visual Studio Code
    • After installation, add code command to PATH:
      1. Open VS Code
      2. Press Cmd+Shift+P to open Command Palette
      3. Type “Shell Command: Install ‘code’ command in PATH”
      4. Select and run the command
      5. Restart terminal and test with code --version
  • Cursor
  • JetBrains Toolbox (PyCharm & IntelliJ)
  • Eclipse
  • Android Studio (Android development)

Terminal Tools

Git GUI Clients

Communication Tools

Database Tools

Design & Collaboration

  • Figma (Design collaboration)

Productivity Tools

DevOps & API Tools

Development & Productivity

Data Science & Analytics

Programming Languages & Frameworks

Java Development

Choose from multiple OpenJDK distributions:

DistributionProvider
Eclipse AdoptiumEclipse Foundation
Amazon CorrettoAmazon Web Services
Azul ZuluAzul Systems
Microsoft Build of OpenJDKMicrosoft
Red Hat OpenJDKRed Hat
Oracle Java JDKOracle Corporation

Configure Java Environment

1
2
3
4
5
6
7

# Set JAVA_HOME (automatic detection)
export JAVA_HOME=$(/usr/libexec/java_home)
export PATH=$PATH:$JAVA_HOME/bin

# Add to ~/.zshrc
echo 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.zshrc
echo 'export PATH=$PATH:$JAVA_HOME/bin' >> ~/.zshrc

Python Development

Choose from multiple Python installation methods:

Download Python from the official website:

  1. Visit python.org/downloads
  2. Download the latest stable version (3.11+ recommended)
  3. Run the installer and follow the setup wizard
  4. Configure PATH:
1
2
3
4
5
6
7
8
9
10

# Python path configuration (adjust version as needed)
export PATH=$PATH:/Library/Frameworks/Python.framework/Versions/3.11/bin

# Add to ~/.zshrc
echo 'export PATH=$PATH:/Library/Frameworks/Python.framework/Versions/3.11/bin' >> ~/.zshrc
source ~/.zshrc

# Verify installation
python3 --version
pip3 --version

Option 2: Homebrew Installation

1
2
3
4
5
6
7
8
9

# Install Python via Homebrew
brew install python

# Verify installation
python3 --version
pip3 --version

# Update pip
pip3 install --upgrade pip

Option 3: UV Package Manager (Modern Approach)

UV is a fast Python package and project manager:

1
2
3
4
5
6
7
8
9
10
11
12
13

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Install multiple Python versions
uv python install 3.10 3.11 3.12 3.13

# List installed versions
uv python list

# Create virtual environment with specific version
uv venv --python 3.11
source .venv/bin/activate

Option 4: Pyenv (Version Management)

Pyenv allows you to easily switch between Python versions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Install pyenv via Homebrew
brew install pyenv

# Add to ~/.zshrc
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc

# Install Python versions
pyenv install 3.11.7
pyenv install 3.12.1

# Set global Python version
pyenv global 3.11.7

# Verify installation
python --version

Essential Python Packages

Install commonly used Python packages:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Upgrade pip first
pip3 install --upgrade pip

# Essential packages
pip3 install virtualenv virtualenvwrapper
pip3 install jupyter notebook ipython
pip3 install requests pandas numpy matplotlib
pip3 install black flake8 pytest  # Development tools

# For web development
pip3 install django flask fastapi

# For data science
pip3 install scikit-learn tensorflow pytorch

Configure Virtual Environments

1
2
3
4
5
6
7
8
9

# Create project virtual environment
python3 -m venv myproject
source myproject/bin/activate

# Install packages in virtual environment
pip install -r requirements.txt

# Deactivate virtual environment
deactivate

Go Development

Download Go and configure:

1
2
3
4
5
6
7
8
9

# Set Go environment variables
export GOROOT=/usr/local/go
export GOPATH=$HOME/go
export PATH=$PATH:$GOROOT/bin:$GOPATH/bin

# Add to ~/.zshrc
echo 'export GOROOT=/usr/local/go' >> ~/.zshrc
echo 'export GOPATH=$HOME/go' >> ~/.zshrc
echo 'export PATH=$PATH:$GOROOT/bin:$GOPATH/bin' >> ~/.zshrc

Maven Build Tool

Download Maven and configure:

1
2
3
4
5
6
7
8
9
10
11

# Extract and move Maven
tar xzvf apache-maven-3.8.5-bin.tar.gz
sudo mv apache-maven-3.8.5 /opt/

# Configure Maven environment
export MAVEN_HOME=/opt/apache-maven-3.8.5
export PATH=$PATH:$MAVEN_HOME/bin

# Add to ~/.zshrc
echo 'export MAVEN_HOME=/opt/apache-maven-3.8.5' >> ~/.zshrc
echo 'export PATH=$PATH:$MAVEN_HOME/bin' >> ~/.zshrc

Protocol Buffers

Download Protocol Buffers and configure:

1
2
3
4
5
6
7
8
9

unzip protoc-3.20.0-osx-x86_64.zip
sudo mv protoc-3.20.0-osx-x86_64 /opt/

# Configure protoc path
PROTOC_HOME=/opt/protoc-3.20.0-osx-x86_64
export PATH=$PATH:$PROTOC_HOME/bin

# Verify installation
protoc --version

Jekyll & Ruby

For static site generation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Install Ruby version manager
brew install rbenv ruby-build
rbenv init  # Follow instructions to add to ~/.zshrc

# Install Ruby and Jekyll
rbenv install 3.4.1
rbenv global 3.4.1
ruby -v

# Install Jekyll
gem install jekyll

# For Jekyll themes (example)
cd your-jekyll-site
bundle install
bundle exec jekyll serve

Git Configuration

Basic Git Setup

Create a Personal Access Token first.

1
2

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

Set up SSH keys for secure, password-free Git operations:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Generate SSH key (replace email with your GitHub email)
ssh-keygen -t ed25519 -C "your.email@example.com"

# When prompted, press Enter to accept default file location
# Enter a secure passphrase when prompted

# Start SSH agent
eval "$(ssh-agent -s)"

# Add SSH key to macOS Keychain
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

# Copy public key to clipboard
pbcopy < ~/.ssh/id_ed25519.pub

Add SSH key to GitHub:

  1. Go to GitHub SSH Settings
  2. Click “New SSH key”
  3. Paste the copied key and give it a title
  4. Click “Add SSH key”

Test SSH connection:

1

ssh -T git@github.com

Configure SSH for automatic keychain use:

1
2
3
4
5
6
7
8

# Create/edit SSH config
nano ~/.ssh/config

# Add these lines:
Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Configure Git Credential Manager (Alternative)

Set up secure credential storage for HTTPS:

1
2
3
4
5
6

# Use macOS Keychain for credential storage
git config --global credential.helper osxkeychain

# When you first push/pull, enter your Personal Access Token instead of password
# It will be automatically cached in the keychain
git clone https://github.com/username/repo.git

Generate Personal Access Token here

DevOps Tools

Containers & Kubernetes

Container Runtimes

Kubernetes Tools

1
2
3

# Install via Homebrew
brew install kubectl helm
brew install --cask lens  # Kubernetes IDE

Monitoring & Observability

AI Development

Quick Setup Script

For experienced users, here’s a comprehensive setup script:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

#!/bin/bash
# macOS Fresh Install Quick Setup

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install essential tools
brew install git node python3 wget

# Install applications
brew install --cask google-chrome visual-studio-code docker
brew install --cask slack zoom notion

# Install development tools
brew install --cask jetbrains-toolbox postman dbeaver-community

# Configure Git (replace with your details)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global credential.helper osxkeychain

echo "Setup complete! Please restart your terminal."

Common Issues & Solutions

Homebrew Installation Issues

  • Error: Command Line Tools not installed
    1

    xcode-select --install

PATH Issues

  • Commands not found after installation
    1
2
3

    # Reload shell configuration
source ~/.zshrc
# Or restart terminal

Permission Issues

  • Permission denied errors
    1
2
3
4
5

    # Use sudo for system-level installations
sudo command_name

# Fix Homebrew permissions
sudo chown -R $(whoami) /usr/local/share/zsh

Git Authentication

  • Authentication failed
    • Use Personal Access Token instead of password
    • Ensure token has appropriate permissions
    • Clear keychain if needed: git config --global --unset credential.helper

Keep Your System Updated

Update Homebrew Packages

1
2
3
4
5

# Update Homebrew and packages
brew update && brew upgrade

# Clean up old versions
brew cleanup

Update macOS

1
2
3
4
5

# Check for macOS updates
softwareupdate -l

# Install updates
softwareupdate -i -a

Update Development Tools

1
2
3
4
5
6
7
8
9
10

# Update Node.js packages
npm update -g

# Update Python packages
pip3 list --outdated
pip3 install --upgrade package_name

# Update UV and Python versions
uv self update
uv python install 3.12  # Install latest versions

Frequently Asked Questions

What should I install first on a new Mac?

Start with Xcode Command Line Tools and Homebrew package manager. These are foundational tools that most other software depends on. Run git --version to trigger Xcode tools installation, then install Homebrew using the official script.

How long does a complete macOS setup take?

A complete developer setup typically takes 2-3 hours, depending on your internet speed and the number of applications you install. The basic setup (Homebrew, Git, Python, Node.js) can be completed in 30-45 minutes.

Should I use Homebrew or download apps manually?

Homebrew is recommended for most installations as it handles dependencies automatically, keeps software updated, and allows easy uninstallation. Use manual downloads only for apps not available via Homebrew or when you need specific versions.

Which Python installation method is best?

For beginners, use the official Python installer from python.org. For advanced users managing multiple projects, pyenv or UV provide better version management. Homebrew Python is good for general development work.

How do I keep my development environment updated?

Run brew update && brew upgrade monthly to update Homebrew packages. Use softwareupdate -l for macOS updates. For Python packages, use pip3 list --outdated to check for updates. Set up a monthly maintenance routine.

What if I encounter permission errors during installation?

Use sudo for system-level installations, but avoid using sudo with Homebrew. If you get Homebrew permission errors, run sudo chown -R $(whoami) /usr/local/share/zsh to fix ownership issues.

Can I use this guide for Apple Silicon (M1/M2) Macs?

Yes, this guide works for both Intel and Apple Silicon Macs. Homebrew automatically detects your architecture and installs the appropriate versions. Some older software may require Rosetta 2 for compatibility.

How do I backup my development environment?

Use brew bundle dump to create a Brewfile listing all installed packages. Export your shell configuration files (.zshrc, .bashrc). Consider using dotfiles repositories on GitHub to version control your configuration.

Conclusion

This comprehensive macOS setup guide provides everything needed for a productive development environment on your fresh Mac installation. From essential developer tools like Homebrew and Git to programming languages like Python and Java, you now have a solid foundation for any development project.

Key takeaways from this guide:

  • Start with fundamentals: Xcode Command Line Tools and Homebrew
  • Use package managers: Homebrew simplifies installation and maintenance
  • Configure your environment: Proper PATH setup and shell configuration
  • Keep everything updated: Regular maintenance ensures security and performance

Bookmark this guide for future reference and share it with fellow developers setting up new Macs. A well-configured development environment is the foundation of productive coding.

What’s Next?

  • Explore macOS productivity tips and shortcuts to boost your workflow
  • Learn about development workflow optimization for your specific tech stack
  • Set up automated backup solutions to protect your development work

Happy coding on your newly configured Mac! 🚀

macos, developer-tools, setup-guide
macos-setup homebrew developer-environment fresh-install productivity-tools
This post is licensed under CC BY 4.0 by the author.