How to Install MBProgressHUD with CocoaPods

CocoaPods has been the standard way to install iOS libraries for years, and it still works well for MBProgressHUD. If your project already uses CocoaPods, adding MBProgressHUD takes one line in your Podfile and one command in the terminal. If your project does not use CocoaPods yet, the setup takes a few extra minutes, but it is still simple. This guide walks through both cases, from the Podfile to the first build.

Before you start, make sure CocoaPods is installed on your Mac. Open the terminal and type pod –version. If you see a version number, you are ready. If you see an error, install CocoaPods first with the command your setup guide recommends, then come back. You also need the GitHub repository address for MBProgressHUD, which is github.com/jdg/MBProgressHUD.git, though CocoaPods finds it by the pod name alone. MBProgressHUD requires iOS 9.0 or later and ARC, which every modern project already uses.

Add the Pod to Your Podfile

Open your project folder in the terminal and look for a file called Podfile. If your project already uses CocoaPods, the file will be there. Open it in a text editor and add one line inside your app target block: pod ‘MBProgressHUD’. If you want to lock the version, write pod ‘MBProgressHUD’, ‘~> 1.2.0’ instead. That version rule means CocoaPods will use 1.2.0 or a later small update, but it will not jump to a new major version without your approval. The latest stable version is 1.2.0, released in January 2020.

If your project has no Podfile yet, create one with the command pod init. That command creates a Podfile with your app target already listed. Open the new file, add the pod line inside the target block, and save it. Make sure the platform line at the top says iOS 9.0 or later. If it says an older version, change it, because MBProgressHUD requires iOS 9.0 or higher.

Run Pod Install and Open the Workspace

Go back to the terminal, make sure you are in your project folder, and run pod install. CocoaPods will download MBProgressHUD and its files, create a Pods project, and link everything to your app. When it finishes, it will tell you to use the workspace file from now on. That file ends in .xcworkspace, and it has the same name as your project.

This step is the one people forget most often. From now on, you must open the .xcworkspace file, not the .xcodeproj file. If you open the project file instead, Xcode will not see the Pods project, and your code will not compile. Close the project file if it is open, then double-click the workspace file. You will see your app project and the Pods project side by side in the navigator.

Import the Library in Your Code

With the workspace open, you can import MBProgressHUD in your code. In Swift, add import MBProgressHUD at the top of the file. In Objective-C, add #import <MBProgressHUD/MBProgressHUD.h> with angle brackets, because the header comes from a framework, not from a file in your project. If you write your app in Swift, you also need use_frameworks! in your Podfile, because Swift projects need CocoaPods to build libraries as frameworks. Add that line at the top of your Podfile if it is not there already, then run pod install again.

Now try a quick test. In a view controller, add a line that shows the HUD, such as MBProgressHUD.showAdded(to: self.view, animated: true) in Swift, or [MBProgressHUD showHUDAddedTo:self.view animated:YES] in Objective-C. Build the project. If it compiles and the HUD appears when you run the app, the install worked.

Common Problems and Quick Fixes

The most common problem is the “no such module” error in Swift. It usually means use_frameworks! is missing from your Podfile, or you opened the .xcodeproj file instead of the .xcworkspace file. Fix the Podfile, run pod install again, open the workspace, and build again. The second most common problem is a deployment target mismatch. If your project targets an iOS version older than 9.0, the pod will not build. Raise the deployment target in your project settings to 9.0 or higher.

Another problem is an outdated CocoaPods installation. If pod install fails with a strange error, update CocoaPods to the latest version and try again. If the Podfile.lock file causes trouble, delete it and the Pods folder, then run pod install fresh. That rebuilds everything from scratch and fixes most broken states.

Updating the Pod Later

When a new version of MBProgressHUD is released, update it with the command pod update MBProgressHUD in the terminal. That command updates only MBProgressHUD and leaves your other pods alone. If you want to update every pod in your project, run pod update without a name, but be careful, because that can change many libraries at once. Because MBProgressHUD has been stable at version 1.2.0 for years, you may never need to update it.

What Pod Install Actually Does

When you run pod install, CocoaPods does more than download one library. It reads your Podfile, finds the version of MBProgressHUD that matches your version rule, downloads the source files, and creates a Pods project next to your app project. It also creates the workspace file that ties the two projects together, and it writes a file called Podfile.lock that records the exact version of every pod you installed.

The Podfile.lock file matters for teams. If you commit it to version control, every developer who runs pod install will get the same versions you have, so the whole team builds with the same code. If you delete it, CocoaPods will pick the newest versions that match your Podfile rules, which can change your build. For a team project, always commit the Podfile.lock file along with the Podfile.

CocoaPods also creates a Pods folder in your project directory, and you should not edit the files inside it. Those files belong to CocoaPods, and the next pod install will overwrite your changes. If you need to change how MBProgressHUD behaves, do it in your own code, not in the Pods folder. Treat the Pods folder as read-only, and your project will stay easy to update.

Here is a short checklist for a clean CocoaPods install:

• Confirm CocoaPods is installed and your Podfile targets iOS 9.0 or later
• Confirm you added pod ‘MBProgressHUD’ inside your app target block
• Confirm you ran pod install and opened the .xcworkspace file, not the .xcodeproj file
• Confirm you added use_frameworks! to the Podfile for a Swift project
• Confirm you import the library and the project builds without errors
• Confirm you know the pod update command for later

Conclusion

Installing MBProgressHUD with CocoaPods is a short job. Add pod ‘MBProgressHUD’ to your Podfile, optionally with the version rule ‘~> 1.2.0’, then run pod install in the terminal. Open the .xcworkspace file, add use_frameworks! for Swift projects, and import the library in your code. The latest stable version is 1.2.0, and it requires iOS 9.0 or later with ARC. If the build fails, check that you opened the workspace, that use_frameworks! is present, and that your deployment target is high enough. With the pod installed, you are ready to show your first loading indicator, and the next guides in this series show you exactly how to do that.

Read next: How to Install MBProgressHUD with Swift Package Manager, How to Show a Loading Indicator with MBProgressHUD, MBProgressHUD Not Working? Common Errors and Fixes