Step by step guide on using Carthage dependency manager

Kevin Le
Kevin Le
Feb 12, 2016 · 4 min read

I just used Carthage dependency manager for the first time. I followed this guide on, but there seems to be a missing step which causes a runtime crash. After some searching and troubleshooting, I eventually got it to work. I just want to document here for future reference and for anyone who might have running to the same problem.

  • Download the latest Carthage pkg and of course run it to install it.
  • Create a new Xcode project and save it (I call my app SnapAuth)
  • Launch a terminal (I use iTerm2)
  • cd to the directory of the project (which is where the xcodeproj file is)
  • Type touch Cartfile
  • Add this following line in the Cartfile file.
github "Alamofire/Alamofire"
  • Type the command below:
carthage update --platform iOS
  • This takes a few minutes, and eventually you’ll see something like
  • In the terminal, type
ls Carthage/Build/iOS

and note the file Alamofire.framework will be listed as we will use it shortly.

  • Back to Xcode, we want to add the above file Alamofire.framework to the Linked Frameworks and Libraries of the project. Do so by dropping the Alamofire.framework file from a Finder window into the drop target (where it says “Add Files here”).
  • Switch to Build Phases tab.
  • Click on + icon and select New run script phase
  • Expand the Run Script section. Once expanded, in the Shell text field, type
/usr/local/bin/carthage copy-frameworks

Click on the + button under Input Files and type

  • Check both checkboxes as shown in the picture above.
  • Now, do a Product->Build. This will succeed.
  • Run the app and it will fail. The error says
dyld: Library not loaded: @rpath/Alamofire.framework/Alamofire
Referenced from:...
Reason: image not found

This is what I was talking about. There seems to be a missing step in the guide on site. This might be due to an older version of Xcode or some other reasons. Anyway, to fix the problem, here is the missing step:

  • Navigate to Build Phases tab
  • Click on the + button and select New Copy Files Phase
  • Expand the Copy Files section.
  • For Destination dropdown, select Frameworks.
  • Drop the Alamofire.framework file in the drop target (where it says “Add Files here”). When prompted, check the Destination: Copy items if needed checkbox.
  • Also make sure the checkbox Code Sign On Copy is checked. Leave the Copy only when installing box unchecked.
  • Now the app will run without crashing. If I need to add one more dependency, I would just add a new line in the Cartfile file. Let’s say I want to add the SnapKit dependency. My Cartfile file now looks like
github “Alamofire/Alamofire”github “SnapKit/SnapKit” >= 0.15.0
  • Run this command again
carthage update --platform iOS

The file SnapKit.framework will be generated. Confirm by typing this ls command in the terminal

ls Carthage/Build/iOS

Now, there are 3 places in Xcode to edit.

  • In the General tab, Linked Frameworks and Libraries section, add the SnapKit.framework as shown below:
  • In the Build Phases tab, Run Script section and Copy Files section:

That’s all. Write your code as normal. Import Alamofire and SnapKit in your code and use them wherever it makes sense, and the app will continue to work without crashing.

Kevin Le

Written by

Kevin Le

My goal is to solve problems in software. Read my shorter posts (possibly duplicated from here but not always)

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade