How to Rename an iOS App in Xcode Without Breaking the Build

Why this happens

An iOS app has several names, and Xcode stores each one in a different place. The project name is the .xcodeproj on disk. The target name feeds PRODUCT_NAME, which becomes the .app bundle and the executable inside it. The label under the icon comes from CFBundleDisplayName in the Info.plist, falling back to CFBundleName and then to the executable name. The bundle identifier is another string entirely, and the App Store name lives in App Store Connect, not in your project at all.

So “rename my app” can mean any of these. Changing one leaves the others untouched, which is why people rename the project and still see the old label on the Home screen — or worse, change the bundle identifier and ship what is effectively a brand-new app.

Xcode’s rename refactor covers the first group: project, target, product name, scheme and the folder on disk. The rest you do by hand.

How to fix it

1. Rename the project and target with Xcode’s rename dialog

This is the safest path, and the one that updates the references inside project.pbxproj.

1. In the Project navigator, click the blue project icon once to select it, then click the project name again (or press Enter) so the text becomes editable.
2. Type the new name and press Return.
3. Xcode shows a Rename dialog listing everything it plans to change: the project, targets, scheme names, the folder on disk, and references in comments. Uncheck anything you want to keep.
4. Accept the offer to take a snapshot first. It costs a second and gives you a way back.
5. Click Rename.

If your target uses PRODUCT_NAME = $(TARGET_NAME) — the default — the built product follows the target automatically. If it is hard-coded, fix it under Targets → your target → Build Settings → search Product Name → Packaging. Set it to the new name, or back to $(TARGET_NAME).

Then run Product → Clean Build Folder (Shift-Cmd-K), delete the app from the simulator or device, and run again.

2. Change only the name under the icon

If the project name is fine and you just want a different label on the Home screen, do not rename anything. Set the display name.

For a target with a hand-managed Info.plist, add or edit:

<key>CFBundleDisplayName</key>
<string>My New Name</string>

For a target using a generated Info.plist (Xcode 13 and later, GENERATE_INFOPLIST_FILE = YES), open the target’s Info tab, add the Bundle display name key, and Xcode writes it as a build setting:

INFOPLIST_KEY_CFBundleDisplayName = My New Name

You can also set that directly in Build Settings by searching for Display Name. Keep it short — iOS truncates long names under the icon, and Apple recommends keeping CFBundleName to 15 characters or fewer.

After changing it, delete the old app from the device or simulator and rebuild. SpringBoard caches the icon label, so an over-the-top install can keep showing the old name.

3. Rename the scheme

Xcode’s rename dialog usually renames the scheme too, but check. A stale scheme breaks xcodebuild -scheme OldName in CI and any Run/Test/Archive action bound to it.

Open Product → Scheme → Manage Schemes. Click the scheme name, press Enter, type the new name, press Enter again, then Close. If the scheme is shared (the checkbox in the Shared column), commit the renamed .xcscheme file under xcshareddata/xcschemes.

4. Clean up what the rename missed

The refactor does not touch these, and each one can break the build or the upload:

• Bundle identifier. Still com.yourcompany.OldName after the rename. Change it in Targets → General → Identity, but only if the app has not shipped. A new bundle identifier is a new app: existing users get no update, and App Store Connect treats it as a separate record.
• Entitlements and capabilities. The .entitlements filename and its App Group strings may still reference the old name. Check Signing & Capabilities.
• Bridging header and Objective-C imports. #import "OldName-Swift.h" becomes #import "NewName-Swift.h". The same applies to @import OldName; in any module that consumed your framework.
• Test targets. TEST_HOST and BUNDLE_LOADER point at the old .app path.
• Extensions. Widgets, App Clips and watch apps have their own display names and bundle identifiers derived from the parent. Rename them individually.
• Scripts and CI. Fastlane lanes, xcodebuild invocations, Podfile target names, .xcconfig files and any hard-coded path.

A quick sweep for leftovers:

grep -rn "OldName" . \
  --include="*.pbxproj" --include="*.plist" \
  --include="*.xcconfig" --include="*.swift" \
  --include="*.m" --include="*.h" --include="*.yml"

Also use Find → Find in Project (Cmd-Shift-F) for the old name and read each hit before changing it.

5. If you only need a different App Store name

The name on the product page is not in your project. Change it in App Store Connect → your app → App Information → Name. It has to be unique across the store, and the change ships with your next version. The bundle identifier stays as it is.

How to prevent it

• Decide the display name before the first upload; the bundle identifier is permanent once the app is on the store.
• Keep PRODUCT_NAME = $(TARGET_NAME) so the product follows the target instead of drifting.
• Set CFBundleDisplayName explicitly instead of relying on the fallback chain.
• Rename through Xcode’s dialog, never by editing project.pbxproj or renaming the .xcodeproj in Finder.
• Take the snapshot Xcode offers, and commit before renaming so you can diff what changed.
• After any rename, do a clean build and an archive — not just a Run — before you tag a release.

FAQ

Does renaming the Xcode project change the App Store name?

No. The App Store name is set in App Store Connect under App Information. Renaming the project only changes local names: the .xcodeproj, the target, the built .app and, if you do not override it, the label under the icon.

Why does the old name still appear under the app icon?

Either CFBundleDisplayName still holds the old value, or the device is showing a cached label. Check the Info tab or Info.plist first, then delete the app from the device, clean the build folder and reinstall.

Can I change the bundle identifier after the app is live?

Not for the same app record. A different bundle identifier is a different app: it installs alongside the old one, inherits no reviews or updates, and needs its own App Store Connect record. Change it before the first submission, not after.