Safely Refactor: The Definitive Guide to Change Project Name in Xcode

Safely renaming an Xcode project involves a systematic process of modifying the Project Name in the navigator, manually renaming source folders in the file system, and updating build configurations to resolve inevitable reference errors. Changing a project name is more than just editing a text label; it requires a deep refactoring of the `.xcodeproj` file, `Info.plist` paths, build schemes, and potentially the Bundle Identifier to ensure the app compiles and launches correctly. By following a strict sequence—starting with the internal project reference and moving to the physical directory structure—developers can avoid the dreaded “linker command failed” errors that often plague this procedure.

The difficulty lies in the disconnection between Xcode’s logical structure (Groups) and the operating system’s physical structure (Folders), meaning a change in one does not automatically reflect in the other. When you rename a project, Xcode attempts to update internal references, but it often leaves behind hardcoded paths in Build Settings, specifically regarding bridging headers and property lists. Furthermore, third-party dependency managers like CocoaPods or Carthage rely on specific target names, which breaks the build environment immediately upon renaming if not properly handled.

Conceptually, it is crucial to distinguish between the “Display Name,” which is simply the string visible to users on the iOS Home Screen, and the “Project Name,” which dictates the file hierarchy and module names. While changing the Display Name is a trivial edit in the `Info.plist` or General settings, changing the Project Name alters the fundamental identity of the codebase. This distinction is vital because a superficial change affects user experience, while a root refactor affects the entire development lifecycle and Continuous Integration (CI) pipelines.

Before attempting this refactor, it is imperative to secure a restoration point, as a single misstep can render the project unopenable. Detailed below is the definitive, step-by-step guide to navigating this complex refactoring process, covering everything from the Project Navigator to deeply buried Build Settings and CocoaPods management.

Is It Possible to Rename an Xcode Project Without Breaking the Build?

Yes, it is possible to rename an Xcode project without breaking the build, provided you follow a specific sequence of steps involving the Project Navigator, folder management, and Build Settings updates.

Specifically, simply typing a new name into the file is rarely sufficient; you must meticulously realign the internal file references with the physical storage on your disk. The root attribute governing this process is the interaction between the Project Navigator and the File Inspector. Xcode relies on a file called `project.pbxproj` to track where every image, swift file, and configuration file lives. When you rename the project, you are essentially modifying this database. If you do so haphazardly, you will encounter “Missing File” errors (indicated by red text in the navigator) or linker errors where the compiler cannot find the entry point for the application.

Critical Warning: You must create a backup or commit your current state to Git before starting. Because this process involves modifying the file structure and the project configuration file simultaneously, there is a high risk of corruption if Xcode crashes or if a step is missed. A Git commit ensures you can run `git reset –hard HEAD` and return to a working state instantly. Furthermore, understanding the concept of “Project Name” versus “Display Name” is essential. The Display Name (found in Target > General > Identity) is what the user sees under the app icon. Changing this is safe and easy. The Project Name, however, changes the `.xcodeproj` filename, the root folder name, and the module name used in code (e.g., `import OldName`). This guide focuses on the latter—the deep structural change.

How Do You Rename the Project File Using the Project Navigator?

Renaming the project file using the Project Navigator involves a multi-step process that starts with selecting the root project node, entering the new name, and confirming the mass-refactor dialog that Xcode presents.

To start, this is the entry point for the entire refactoring operation. The Project Navigator (the left-hand sidebar) displays the root icon of your project, usually a blue blueprint icon. This item represents your `.xcodeproj` file. The process here is deceptively simple but triggers a cascade of internal changes. You must click this name slowly twice (or select it and press “Enter”) to make the text editable. Once you type the new name and hit Enter, Xcode does not just change that one string; it initiates a project-wide search to find associated targets and build configurations that share that name.

Next, you must perform a visual check of the changes. Immediately after confirming the rename, you will notice that the text next to the blue icon changes. However, you will likely see that the folders (Groups) underneath it still retain the old name. This is normal behavior. Xcode changes the logical container but does not touch the physical folders yet. Additionally, you will see the “Scheme” (the dropdown menu next to the Play/Run button) might automatically update, or it might create a new scheme with the new name. It is vital at this stage not to panic if the build fails immediately; this is only the first step of the synchronization process between Xcode and the file system.

What Dialog Boxes Should You Accept During the Rename?

The “Rename Project Content” dialog box is a critical prompt that lists all targets, plist files, and build configurations Xcode intends to rename, and you must accept this by clicking “Rename” to ensure internal references update automatically.

To illustrate, when you press “Enter” after typing the new project name, Xcode pauses and presents a sheet titled “Rename Project Content.” This is not a generic confirmation box; it is a checklist of proposed changes. It will typically suggest renaming the app target, the test targets (e.g., `OldNameTests` to `NewNameTests`), and the product bundle name. More specifically, rejecting this dialog or hitting “Cancel” will leave your project in a hybrid state where the filename is new, but the internal “Targets” are old. This mismatch is a primary cause of build failures. You should review the items in the list—usually, every checkmark should be enabled. By clicking “Rename,” you allow Xcode to rewrite lines inside the `project.pbxproj` file, saving you hours of manual editing.

Does Xcode Automatically Rename the Root Directory?

No, Xcode does not automatically rename the physical root directory or the source folders on the disk when you rename the project in the Navigator.

To explain further, this is the most confusing aspect for beginners. When you look at Xcode, you see “Groups” (yellow folder icons), which are virtual organizational tools. When you look at Finder, you see “Folders,” which are physical storage locations. After you complete the rename step in Xcode, your `.xcodeproj` file will change names (e.g., `NewName.xcodeproj`), but it will still be sitting inside a folder named `OldName`, and your source code will likely be inside a subfolder named `OldName`. Consequently, if you stop here, your project is messy: the file name doesn’t match the folder name. To achieve a clean refactor, you must manually rename these folders in Finder, which leads to the “Missing Files” issue that must be resolved in the next major step.

How Do You Rename Source Folders and Groups Correctly?

Renaming source folders and groups correctly requires a three-step grouping process: renaming the physical folder in Finder, handling the resulting “missing file” errors in Xcode, and using the Identity Inspector to relink the Xcode group to the new folder path.

First, you must close Xcode completely. This ensures that the application doesn’t try to write to files you are about to move. Navigate to your project directory in Finder (the file system). You will likely see a folder with the old project name containing your `.swift` files, `Assets.xcassets`, and `Info.plist`. Rename this folder to your desired new name. Next, when you re-open Xcode, you will immediately see that the Group (the yellow folder icon in the sidebar) that represented that folder has turned red or the files inside it have turned red. This indicates a “broken link.” Xcode is looking for `…/OldName/ViewController.swift`, but that path no longer exists.

Afterwards, you must fix this link using the Identity Inspector. Select the Group that corresponds to the folder you just renamed (it will likely still have the old name in the navigator). Rename the Group itself to match the new name. Then, look at the right-hand sidebar (Inspectors panel) and select the “File Inspector” icon (looks like a page). Look for the “Location” area. You will see a small folder icon. Click this icon. A file selection window will appear. Navigate to and select the folder you renamed in Finder. Specifically, once you choose the new folder, Xcode will re-scan the directory and re-establish the links. The red text should verify into black text, confirming the source code is properly linked again.

How to Relink the “Info.plist” After Changing Folder Names?

The Info.plist file is a definition file containing essential app configuration data, and relinking it requires updating the file path in the “Build Settings” under the “Packaging” section to match the new folder structure.

More specifically, even after you relink the folders in the Navigator, the build system often holds onto the old path for the `Info.plist`. If you try to build now, you will likely get an error saying “ProcessInfoPlistFile: Info.plist not found.” To illustrate, navigate to your Project Target (click the root blue icon, then select the Target in the center panel). Click on the “Build Settings” tab. In the search bar, type `Info.plist`. You will see a setting named “Info.plist File.” It will likely say `OldName/Info.plist`. You must manually double-click this value and change it to `NewName/Info.plist`. This tells the compiler exactly where to find the configuration file in the newly renamed directory structure.

How to Update “Bridging Headers” Paths in Build Settings?

Updating “Bridging Headers” involves locating the `SWIFT_OBJC_BRIDGING_HEADER` setting in Build Settings and manually modifying the path string to reflect the new project directory name.

For example, if your project mixes Swift and Objective-C code, Xcode uses a bridging header to allow the two languages to communicate. This file path is hardcoded in the project settings, similar to the `Info.plist`. If you rename the folder containing this header, the compilation will fail with “Bridging Header not found.” Specifically, go to Build Settings and search for “Bridging Header.” You will find a path like `OldName/OldName-Bridging-Header.h`. You must edit this string to match your new folder name (e.g., `NewName/NewName-Bridging-Header.h`). Failing to do this will cause every Swift file that references Objective-C classes (or vice versa) to throw “Use of unresolved identifier” errors.

How Do You Update the Scheme and Bundle Identifier?

Updating the Scheme and Bundle Identifier involves grouping steps to rename the build configuration via “Manage Schemes” and modifying the unique app ID in the “General” settings to ensure the app is recognized correctly by the OS and App Store.

To start, the “Scheme” is the configuration that tells Xcode what to build (Debug vs. Release) and which executable to launch. Often, after renaming the project, the Scheme retains the old name (e.g., you see “OldName” next to the simulator list). To fix this, go to the top menu bar, select Product > Scheme > Manage Schemes. In the dialog that appears, you will see a list of schemes. Click once on the old name to select it, then click again (slowly) to rename it to match your new project name. This ensures consistency across your development environment.

Crucial for IPA Modders, changing the Bundle Identifier is perhaps the most significant step if you are refactoring for the purpose of cloning an app or creating a new distribution. The Bundle ID (e.g., `com.company.oldname`) is the DNA of the app in the Apple ecosystem. If you install an app with the same Bundle ID as one already on the phone, the OS will overwrite the existing one. If you want the new project to exist as a separate app, go to the Target > General tab. Under the “Identity” section, locate “Bundle Identifier.” Update this to `com.company.newname`. Furthermore, changing this ID dissociates the app from any previous provisioning profiles or App Store Connect entries, so you will need to ensure your signing capabilities are updated to match the new ID.

What Steps Are Required If the Project Uses CocoaPods?

If the project uses CocoaPods, the required steps involve deleting the existing workspace and lockfile, updating the target name within the `Podfile`, and running `pod install` to regenerate the dependency structure.

Specifically, CocoaPods creates a wrapper around your project called a `.xcworkspace`. This workspace relies heavily on the specific file paths and target names of your project. When you rename the project file (from `Old.xcodeproj` to `New.xcodeproj`), the workspace loses its reference to the project. Step 1 is to clean the slate. Close Xcode. Open Terminal or Finder and navigate to the project folder. You should delete the `.xcworkspace` file and the `Podfile.lock` file. These are generated files and will be recreated.

Step 2 requires editing the `Podfile` itself. Open the `Podfile` in a text editor (like TextEdit or VS Code). You will see a line that says `target ‘OldName’ do`. You must change this string to match your new target name: `target ‘NewName’ do`. If you have test targets inside the Podfile, update those as well. Step 3 is the regeneration. Open Terminal, navigate to your directory, and run `pod install`. CocoaPods will analyze the folder, find the newly renamed `.xcodeproj`, read the updated Podfile, and generate a fresh `.xcworkspace` that links everything correctly.

Should You Run “pod deintegrate” Before Renaming?

Yes, running “pod deintegrate” before renaming is safer because it completely removes CocoaPods configurations from the Xcode project file, ensuring a clean slate for the refactoring process.

To illustrate, `pod deintegrate` is a command that reverses `pod install`. It strips all CocoaPods shell scripts, file references, and build phases from your `.xcodeproj` file. If you attempt to rename a project that is still heavily intertwined with CocoaPods, Xcode might struggle to rename certain locked references, or the old Pods target might persist, causing duplicate symbols or linker errors. More specifically, by running `pod deintegrate` first, you return your project to a “vanilla” state. You can then perform all the renaming steps (Project, Folders, Schemes) without interference. Once the project is successfully renamed and compiling on its own, you then re-add CocoaPods as if it were a fresh integration. This method significantly reduces the variable count when troubleshooting refactoring errors.

How Do You Change the App Display Name Without Renaming the Project?

Changing the app’s display name only requires modifying the “Bundle Display Name” property within the configuration settings, leaving the underlying project structure and file system names completely untouched.

Furthermore, distinguishing between the internal Project Name and the external Display Name is critical for developers who want to update branding without risking the stability of their codebase. The Project Name dictates the file hierarchy, build settings, and bundle identifiers, which are deeply integrated into the source code. In contrast, the Bundle Display Name is purely cosmetic; it is the label users see under the app icon on the iOS Home Screen. Modifying the display name is a low-risk operation often performed when “skinning” apps or creating white-label versions, whereas renaming the project involves complex refactoring of directories and schemes.

Where is the “Bundle Display Name” Located in Xcode?

To change the user-facing name of your application, you must locate the specific key within the project’s information property list. This does not alter the binary name, only the label presented by the operating system.

To locate and modify this property, follow these steps:

• Navigate to the Target: Select your project file in the Project Navigator, then select your app’s Target in the main editor window.
• Access the Info Tab: Click on the “Info” tab (not the “General” tab) to view the Custom iOS Target Properties.
• Modify the Key: Look for `Bundle display name` (or the raw key `CFBundleDisplayName`). If it does not exist, add a new row, select this key, and enter your desired app name in the value column.

Troubleshooting Common Errors After Renaming in Xcode

Most post-renaming errors stem from stale cache data or broken file paths, which can usually be resolved by performing a “Clean Build Folder” operation or manually clearing Derived Data.

Additionally, even after a seemingly successful refactor, developers often encounter build failures because Xcode continues to reference old directory structures. The first line of defense is always the Clean Build Folder command (Shift + Cmd + K), which forces Xcode to recompile the project from scratch. However, if issues persist, the problem often lies within DerivedData—a folder where Xcode stores intermediate build results and indexes. If this cache retains references to the old project name, it causes conflicts. Manually deleting the contents of the `~/Library/Developer/Xcode/DerivedData` directory ensures that the IDE rebuilds the project index using strictly the new naming conventions.

How to Fix “Linker Command Failed with Exit Code 1” After Renaming?

This error is essentially the compiler stating that it cannot find the executable code or libraries it expects to link together, often because the Search Paths still point to the old project directories.

To resolve linker errors after a rename, investigate the following settings:

• Check Framework Search Paths: Navigate to Build Settings and verify that “Framework Search Paths” do not contain hard-coded paths referencing the old project folder.
• Verify Test Targets: Unit Test and UI Test targets often lose their connection to the main “Host Application.” Ensure the “General” settings for your test targets point to the renamed app target.
• Inspect Linker Flags: Look for “Other Linker Flags” in Build Settings to ensure no scripts or flags are manually referencing the previous binary name.

Why Does the App Icon Disappear After Renaming?

The disappearance of the app icon usually indicates that the link between the build target and the Asset Catalog (Assets.xcassets) was severed during the file migration process.

To restore the app icon, ensure the asset catalog is correctly associated:

• Check Target Membership: Select your `Assets.xcassets` file in the Project Navigator and ensure the box next to your app target is checked in the File Inspector (right panel).
• Verify App Icon Source: Go to the target’s “General” tab, scroll to “App Icons and Launch Images,” and ensure “App Icon Source” is set to the correct icon set name (usually “AppIcon”).
• Re-add the File: If the file path is broken in the project file, remove the `Assets.xcassets` reference (delete, but choose “Remove Reference”) and drag the folder back into Xcode to re-establish the file path.