Learn how to add new dependencies to an existing Podfile, pin versions safely, and update pods with the right commands so your iOS project stays stable and reproducible.
This guide assumes CocoaPods is already installed and your project already has a Podfile and a generated .xcworkspace. If not, set that up first before adding more dependencies.
All the work here happens in two places: the Podfile you edit by hand, and Terminal where you run the pod commands. Keep both handy.
Work on a clean Git state if you can. That way, if an update changes something unexpectedly, you can review the diff and roll back easily.
Understanding the difference between pod install and pod update is the core skill this guide teaches, so pay special attention to that distinction later on.
Open your Podfile and, inside the appropriate target block, add a new line such as pod 'NewLibrary'. Place it alongside your existing dependencies.
Save the file, then run pod install from the project root. Despite the name, pod install is the correct command for adding a new dependency, not pod update.
CocoaPods resolves a compatible version, downloads it, and updates both your workspace and the Podfile.lock. Existing pods that are already locked stay at their current versions.
Reopen or return to your .xcworkspace, add the import for the new library, and build to confirm it integrated. Commit the updated Podfile and Podfile.lock together.
How you specify a version controls how much freedom CocoaPods has to move. Being deliberate here prevents surprise breakage.
An exact pin like pod 'Library', '1.4.2' locks to that single version. Nothing moves until you change it, which maximizes stability but means you manually adopt fixes.
The optimistic operator, written pod 'Library', '~> 1.4', allows compatible updates within a range while blocking major-version jumps that might break your code. It is a common balance between safety and staying current.
You can also target a Git source directly, pointing at a branch, tag, or commit. That is powerful for testing forks or unreleased fixes, but pinning to a specific commit is safest for reproducibility.
This distinction trips up almost everyone at first, so internalize it. The two commands do genuinely different things.
pod install respects the Podfile.lock. It installs exactly the locked versions where they exist, and only resolves fresh versions for pods that are new or not yet locked. Use it after editing the Podfile and when setting up the project on a new machine.
pod update deliberately ignores the lock for the pods you name and pulls the newest versions allowed by your Podfile constraints. Running a bare pod update with no arguments tries to update everything at once.
As a rule, use pod install day to day, and reach for pod update only when you intentionally want to move dependencies forward.
When you want to update just one library, name it explicitly: pod update LibraryName. This updates only that pod and its dependencies, leaving everything else pinned.
Updating one pod at a time is far safer than updating everything. It keeps the change surface small, so if something breaks you know exactly which library caused it.
After the command runs, build in the workspace and run your tests. Read any release notes for that library, especially if the version crossed a major boundary.
Review the Podfile.lock diff before committing. It shows precisely which versions changed, which is a valuable record for your team and for debugging later regressions.
Run pod outdated to see which of your dependencies have newer versions available. It lists the current, requested, and latest versions for each pod.
This is a read-only report, so it is completely safe to run any time. Use it to plan updates rather than blindly running a full pod update.
Cross-reference the output with your version constraints. A pod might have a newer release that your ~> constraint intentionally blocks because it is a major version.
Treat dependency updates as deliberate maintenance work. Batching them into scheduled review, rather than reacting randomly, keeps your project predictable.
To remove a dependency, delete its line from the Podfile and run pod install. CocoaPods will detach the library and clean up the integration.
Also remove any import statements and code that referenced the library, or your project will fail to compile. The compiler errors will point you to the leftover usages.
After removal, build the workspace to confirm everything still links. A clean build folder can help if you see stale references.
Commit the resulting changes. A smaller dependency graph means faster builds and fewer things that can break during future updates.
Many pods depend on other pods, and CocoaPods resolves that whole graph for you. When you add one library, you may see several additional entries appear in the Podfile.lock that you never listed yourself.
These are transitive dependencies, pulled in because a library you asked for needs them. They are managed automatically, so you generally should not declare them yourself unless you need a specific version.
Conflicts arise when two of your direct pods depend on incompatible versions of the same shared library. The resolver will stop and tell you what clashes.
When that happens, read the message closely, then loosen a constraint or update one of the conflicting pods to a release that agrees on the shared version. Keeping your direct dependencies reasonably current is the simplest way to avoid these standoffs.
Always commit the Podfile.lock. It is the contract that keeps every machine and CI runner on identical versions, and skipping it reintroduces dependency drift.
Prefer the ~> constraint for most libraries. It lets you receive compatible bug fixes while protecting you from breaking major upgrades you have not vetted.
Update intentionally and one library at a time when possible, then test. Large simultaneous updates make regressions hard to trace.
Finally, remember CocoaPods only manages libraries. It does not generate app logic, replace Xcode, or remove the need for the Apple Developer Program when you ship. It simply keeps your dependencies orderly and reproducible.
A frequent source of confusion is the difference between pod install and pod update.
pod install resolves dependencies against the versions already pinned in your Podfile.lock, installing exactly those. pod update ignores the lock for the named pods and moves them to the newest versions your Podfile constraints allow, then rewrites the lock.
The practical rule: run pod install for everyday work and after pulling changes, and reserve pod update for when you deliberately want to upgrade.
Always commit Podfile.lock to source control. It is what guarantees every teammate and your CI build the identical dependency versions, preventing the classic works-on-my-machine drift.
pod install respects the Podfile.lock and only resolves new or unlocked pods, so use it for everyday work and adding dependencies. pod update ignores the lock for named pods and pulls newer versions, so use it only when you deliberately want to move dependencies forward.
Add a pod line inside the target block of your Podfile, then run pod install. Even though you are adding rather than updating, pod install is the correct command. Then build in the .xcworkspace and commit the updated Podfile and Podfile.lock.
Run pod update followed by the specific library name, for example pod update LibraryName. This updates only that pod and its dependencies, leaving everything else locked, which keeps your change surface small and easier to debug.
Run pod outdated. It is a read-only report listing your current, requested, and latest available versions for each pod, so you can plan updates without changing anything.
The optimistic operator, written like '~> 1.4', is a common default because it allows compatible updates while blocking major-version jumps. Use an exact version pin when you need maximum stability.