Build an iOS Development Environment on Mac From Scratch: A Complete Tutorial from Xcode, Homebrew, Git, CocoaPods to Your First App

Homebrew’s official installation guide lists three prerequisites: a supported Mac, a compatible processor, and Xcode Command Line Tools. For a reliable Mac iOS development environment, install and launch Xcode first, then configure Homebrew and Git; install CocoaPods only if your project requires it. Finish by creating an app in Xcode and running it in a simulator or on a suitable device.

This guide is for you if you’re new to iOS development on Mac, restoring a development setup, or checking whether a local or remote Mac can build and run an app. It follows the actual setup sequence and gives you a way to pinpoint where a failed build or launch is coming from.

Your goal: verify each tool as you install it, then use a successful app build and launch as the final proof.

Mac iOS development environment: check compatibility before installing tools

Start with the Mac you have, not with an installer. Xcode releases have specific macOS compatibility requirements. Check Apple’s Xcode system requirements for the version you plan to install. If your macOS version falls outside that release’s requirements, choose a compatible Xcode release or update macOS when appropriate. Don’t assume the latest Xcode will run on every Mac.

Check these conditions before downloading anything:

• macOS version: Open the Apple menu, choose About This Mac, and note the macOS version. Compare it with Apple’s requirements for the Xcode release you intend to use.
• Available storage: Check System Settings → General → Storage. Leave room for Xcode, simulator runtimes, project files, and derived build data. If space is tight, avoid installing extra simulator components until you need them.
• Account permissions: Make sure your macOS account can install applications and approve system prompts. If this is a managed work Mac, ask your administrator before changing developer tools or installing packages.
• Apple account and test target: You can begin learning and test a basic app in an iOS simulator without treating a physical iPhone or paid developer membership as a universal prerequisite. Device testing, signing, and certain Apple developer services can introduce account requirements. Check Apple’s developer account overview for the account options relevant to your use.

The simulator is a sensible first target: it lets you verify a project build and app launch without connecting a device. Use a physical device when you need to check behavior that depends on real hardware or device-specific configuration. Keep signing and account setup as a separate troubleshooting step if the simulator works but a device build does not.

Homebrew and Git support the workflow; neither replaces Xcode. CocoaPods is a project dependency manager, not a general prerequisite for every iOS app.

First, install and initialize Xcode

How should you install and initialize Xcode on a fresh Mac? Get Xcode through an official Apple channel, then launch it and complete the setup prompts before trying to build a project.

Apple’s Xcode resources page links to the official download options. Choose a release that matches the macOS compatibility you checked earlier. If you install Xcode through the Mac App Store, wait for the download and installation to finish before opening it. If you use Apple’s developer downloads, use the official instructions for that download.

On first launch, Xcode may request additional components or ask you to accept a license. Complete the prompts and let component installation finish. Apple explains how to install additional Xcode components. The exact prompts can vary with the Xcode release and what is already installed, so follow the screen rather than relying on a command copied from an unrelated setup.

Then verify that the command-line tools point to a working developer directory:

xcode-select -p
xcodebuild -version

The first command reports the selected developer directory. The second prints the Xcode build-tool version. If the path is missing, points to a different installation, or the command reports that Xcode is not configured, open Xcode and complete setup first. If you have multiple Xcode installations, select the intended one using Apple’s documented command-line tool setup guidance.

Xcode matters beyond its editor. It supplies the iOS SDK and connects the project to build tools and simulator components. A successful download alone doesn’t prove that these parts are ready: complete first launch and verify the command-line tools before adding more software.

Then, configure Homebrew and Git

How do you configure Homebrew and Git without confusing their roles? Install Homebrew from its official instructions, verify it, then check Git and set the identity Git should use for your commits.

The Homebrew installation page explains the current installation method and its prerequisites. Read that page and use the command shown there, rather than running an installer copied from an old tutorial. After installation, follow its instructions for adding Homebrew to your shell environment if it asks you to do so. Then check:

brew --version

If the shell cannot find brew, revisit the setup instructions and check that the required shell configuration was applied. Don’t reinstall immediately; a missing PATH entry can make an installed command appear unavailable. For managed Macs, confirm your administrator permits the installation before changing system or shell configuration.

Git may already be available through the developer tools, or you may install it using an option in the official Git for Mac installation guidance. Check what your shell can access:

git --version

Set a name and email for commits. Use the identity you want recorded in project history:

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

These settings identify commits; they do not sign you in to a hosting service. If you share the Mac with another developer, consider whether global settings are appropriate. You can instead set repository-specific values from inside a project directory by omitting --global.

Choose the next step based on the project, not on a generic setup checklist:

• If the project documentation specifies Swift Package Manager, use Xcode’s package dependency workflow. Apple explains how to add package dependencies to an app.
• If the project includes a Podfile or explicitly requires CocoaPods, install CocoaPods according to its official instructions and use the project’s documented workflow.
• If you’re starting a simple app with no third-party dependencies, skip CocoaPods for now. You can add dependency tooling when a real project calls for it.

Add CocoaPods only when the project needs it

When should you install CocoaPods? Install it when the project’s own dependency instructions use CocoaPods, not merely because you are setting up an iOS Mac.

Check the repository before installing anything. A Podfile, project documentation that says to run pod install, or a team setup guide that names CocoaPods indicates that the project expects this workflow. If the project instead uses Swift Package Manager, adding CocoaPods creates extra setup without helping you build that project.

When CocoaPods is required, follow the official CocoaPods getting-started guide for installation options and environment requirements. Ruby and package-manager configurations can differ between Macs, so don’t assume a command that worked on someone else’s computer is the right choice for yours. If the project manages tool dependencies through Bundler, follow its instructions rather than installing an unrelated global version.

From the project directory, the usual workflow is:

pod install

Read the command output. If it reports that dependencies were resolved and generates a workspace, open the generated .xcworkspace in Xcode rather than continuing with the original .xcodeproj. The workspace brings the app project and its CocoaPods integration together. Check the project’s own readme or setup guide if it specifies a different process.

If dependency resolution fails, locate the first meaningful error in the output. Check that you’re in the directory containing the expected Podfile, confirm the required Ruby and CocoaPods setup, and compare the requested dependencies with the project’s documented versions. Avoid deleting lockfiles or changing dependency versions as a first response; those changes can affect the whole team.

Create and run your first app in Xcode

How do you create and run a first iOS app? Create a minimal iOS project, select a simulator as the initial run destination, build it, and confirm that the app opens. Apple’s Xcode project creation guide describes the project setup flow.

Follow these steps:

• Open Xcode and choose the option to create a new project.
• Select an iOS app template. For a small first test, choose the standard app template rather than a specialized framework or game template.
• Enter a project name and choose the interface and language that match your learning goal or existing project. These choices shape the generated starter code; they don’t change the basic check that the project can build and launch.
• Set an organization identifier and bundle identifier as requested. Use values appropriate to your project. If you’re only learning in the simulator, you don’t need to treat device signing as the first obstacle to solve.
• Save the project in a location you can find again. If you plan to use Git, create a repository or initialize version control for the project.
• Select an available iOS simulator in the run-destination control. If the simulator runtime is missing, install the relevant component through Xcode’s supported component workflow.
• Build and run the app. Wait for the build to finish, then confirm that the app opens in the selected simulator.

A completed build is evidence that Xcode can compile the project with the selected SDK. Seeing the app launch is a separate check: it verifies that the simulator can start the built app. Keep both results. If you need to prove a setup to a teammate, save the build result and a screenshot of the running app alongside the project’s setup notes.

If your project uses CocoaPods, open the generated workspace before building. If it uses Swift Package Manager, allow Xcode to resolve the project’s packages. Don’t mix dependency instructions from a different project type into a fresh template that has no external packages.

Verify the workflow and locate the first failure

A setup is useful only when you can tell which stage is failing. Work from the earliest broken check toward the app launch; changing several tools at once makes the cause harder to identify.

Use this checklist:

• [ ] System: The installed macOS release meets the requirements for your chosen Xcode release.
• [ ] Xcode: Xcode opens, setup prompts are complete, and xcode-select -p and xcodebuild -version return useful results.
• [ ] Homebrew: brew --version works in a new terminal window.
• [ ] Git: git --version works, and the intended commit identity appears in git config --global --list or repository-level configuration.
• [ ] Dependencies: The project’s chosen dependency manager matches its documentation. If it uses CocoaPods, dependency resolution completes and you open the generated workspace.
• [ ] Build: Xcode completes a build for the selected destination.
• [ ] Launch: The app opens in the simulator or on a suitable configured device.

When a check fails, start with the closest relevant evidence:

• Xcode won’t launch or build tools are unavailable: Recheck macOS compatibility, finish Xcode’s first-launch prompts, and verify the selected developer directory.
• A command is “not found”: Check whether the tool is installed and whether the shell environment includes its executable path. Open a new terminal after making shell changes.
• A package cannot be resolved: Confirm the dependency manager expected by the project, then inspect its first reported resolution error and project instructions.
• The build succeeds but the app does not launch: Check the selected run destination and build output. Treat a device signing issue separately from a simulator failure.
• Only one project fails: Compare its setup instructions and dependency files with the working test app before changing the Mac’s global tools.

Remote access doesn’t change this diagnostic order. The Mac still needs a compatible macOS and Xcode setup, enough storage for the project and required components, and a way for you to interact with Xcode and its run destination. If you’re evaluating a remote Mac, check whether its access method supports the interactive steps in this tutorial before relying on it. Hashvps has plan details and a help center you can review for service-specific information; don’t assume a remote environment has a particular configuration until you confirm it.

Choose the right Mac setup for your next project

A local Mac is usually the simplest choice if you already have a compatible machine, need frequent hands-on access, or depend on local peripherals. A remote Mac can make sense when you need a temporary environment for a build or validation run and don’t have a suitable Mac available. Check access method, macOS and Xcode compatibility, storage, and project requirements before choosing one.

The trade-off is concrete: a non-Mac setup can complicate access to Xcode and iOS simulators; a shared or borrowed Mac may not preserve the project’s dependencies and signing setup; and buying a Mac solely for a short test can leave you paying for hardware you rarely use. A remote Mac is not the best fit for every job either: if you need sustained heavy workloads or physical-device connections, a dedicated local Mac may be the better choice.

Use the checklist above to confirm that tools install, dependencies resolve, and the app actually launches. If you don’t have a suitable local Mac for a temporary build or first-run check, compare a Hashvps remote Mac environment against the specific Xcode and access requirements you just verified.