A step-by-step guide to installing CocoaPods on macOS, creating a Podfile, adding your first dependency, and opening the generated .xcworkspace in Xcode.
Before installing CocoaPods, make sure you have Xcode installed from the Mac App Store and that you have opened it at least once to accept its license. CocoaPods relies on the Xcode command line tools.
You also need Ruby, because CocoaPods is distributed as a Ruby gem. macOS ships with a system Ruby, which can work but often causes permission headaches.
A Terminal window is your main workspace for this whole process. Everything here is command-line driven, so get comfortable running commands one at a time and reading their output.
Finally, have an existing Xcode project, or create a fresh one, since CocoaPods integrates into a real .xcodeproj.
In Terminal, run xcode-select --install. If the tools are already present, macOS will tell you so; otherwise it will download and install them.
These tools provide the compilers and Git support that CocoaPods and Xcode both depend on. Without them, later steps can fail with confusing errors.
If you have multiple Xcode versions, make sure the active one is correct. You can point the system at a specific Xcode with sudo xcode-select --switch followed by the path to that Xcode app.
Open Xcode once manually and accept any license prompt. This small step prevents a class of build failures that stump newcomers.
The classic install command is sudo gem install cocoapods, which installs CocoaPods into the system Ruby. It works, but the sudo and system Ruby combination is the source of many permission and compatibility problems.
A cleaner approach many developers prefer is to use a Ruby version manager such as rbenv to install a recent, user-owned Ruby, then run gem install cocoapods without sudo. This avoids touching system files.
Whichever route you choose, let the install finish completely, since it pulls in several supporting gems. This can take a couple of minutes on a fresh machine.
When it completes, verify with pod --version. Seeing a version number printed means the CocoaPods command is on your path and ready.
Navigate in Terminal to your project's root folder, the directory that contains the .xcodeproj file. Getting into the right directory matters, because CocoaPods detects your project from here.
Run pod init. This generates a starter Podfile pre-populated with your target name and a sensible platform line.
The Podfile is the manifest that declares which libraries your app depends on. It is a plain text file you edit by hand, and it is safe and expected to commit it to source control.
Open the Podfile in any text editor. You will see a target block matching your app, ready for you to add dependencies inside it.
Inside the target block, add a line for each library using the pod keyword followed by the library name in quotes, for example pod 'SomeLibrary'. Each dependency gets its own line.
You can control versions with operators. Pinning to an exact version looks like pod 'SomeLibrary', '1.2.3', while accepting compatible updates uses the optimistic operator, such as pod 'SomeLibrary', '~> 1.2'.
Check the uncommented platform line at the top, for example platform :ios, '15.0'. Set this to a deployment target your project actually supports.
If a library requires dynamic frameworks or you are using certain Swift libraries, you may need to uncomment use_frameworks!. The library's own documentation will tell you when that is required.
Save the Podfile, then run pod install from the same directory. CocoaPods resolves compatible versions, downloads the source, and integrates everything into your project.
The first ever run on a machine may take longer because CocoaPods needs to prepare its index of available libraries. Subsequent runs are faster.
When it finishes, CocoaPods prints a message telling you to use the .xcworkspace from now on. It also creates a Podfile.lock recording the exact versions it resolved.
Commit both the Podfile and the Podfile.lock to version control. The lock file is what guarantees your teammates and your CI system get identical dependency versions.
From now on, always open the newly generated .xcworkspace file, never the original .xcodeproj. The workspace ties your app target together with the Pods project so everything links correctly.
Opening the wrong file is the single most common beginner mistake with CocoaPods. If your imports are not found or nothing builds, this is the first thing to check.
Inside Xcode, add an import statement for your library at the top of a Swift file, then build. A successful build confirms the dependency is wired up.
You can close and reopen the workspace freely. As long as you use the .xcworkspace, Xcode will keep resolving the pods correctly.
If the install does not go smoothly, the first thing to check is which Ruby you are actually using. Run ruby --version and which ruby to confirm whether you are on the system Ruby or a version-managed one.
A very common symptom is pod: command not found even though the gem installed. That almost always means the directory holding the pod executable is not on your PATH, so add it in your shell profile and open a fresh Terminal.
Permission errors during gem install usually trace back to writing into system directories. Installing a user-owned Ruby with a version manager sidesteps that entirely.
If pod init or pod install complains, make sure Xcode has been opened once to accept its license and that the command line tools are present. Solving the environment once means later installs are routine.
CocoaPods gets libraries into your project, but it does not write your features. You still author real native Swift or Objective-C code inside Xcode.
This is not a low-code or visual builder. It is a plumbing tool for dependencies, and understanding that keeps your expectations grounded.
When you are ready to ship, you will still build and archive in Xcode, and you will need an active Apple Developer Program membership to distribute through the App Store or TestFlight.
With the workspace open and your first pod building, you now have a repeatable foundation. Adding, updating, and removing dependencies from here follows the same Podfile-then-install rhythm.
Once the gem finishes installing, confirm everything is in place before you rely on it.
Run pod --version in Terminal; a version number means the CLI is on your PATH and ready. If the command is not found, your Ruby gem bin directory may not be on the PATH, which is common when using a version manager.
It also helps to check which Ruby you are using with ruby --version and which ruby. Installing CocoaPods against the macOS system Ruby often triggers permission errors, so many developers prefer a managed Ruby via Homebrew, rbenv, or rvm.
With a managed Ruby you can install the gem without sudo, which keeps your setup clean and avoids the permission problems that send people down long troubleshooting paths later.
macOS ships with a system Ruby that can run CocoaPods, but using a version manager like rbenv to install a user-owned Ruby avoids many permission problems. Either way, CocoaPods requires Ruby because it is a Ruby gem.
sudo gem install cocoapods works but modifies system files and often causes permission issues. Many developers prefer installing a separate Ruby with a version manager so they can run gem install cocoapods without sudo.
CocoaPods creates a workspace that links your app target with the generated Pods project. Opening the original .xcodeproj skips the pods, so imports fail to resolve and nothing links. Always open the .xcworkspace after adding pods.
Yes. Commit both. The Podfile.lock records the exact resolved versions, which guarantees every teammate and your CI build gets an identical dependency graph.
No. CocoaPods only manages third-party dependencies. You still write native code in Xcode and need the Apple Developer Program to publish to the App Store.