How to Completely Rename an Xcode Project and Root Directory

Why this happens

Renaming an Xcode project is rarely a one-click operation. When you change the project name in Xcode’s File Inspector, Xcode updates the .xcodeproj file bundle, primary build targets, and compilation schemes. However, it intentionally leaves physical folders on disk untouched to avoid breaking absolute paths and external script dependencies.

Because the underlying folder names remain unchanged, your repository ends up with mismatched names—such as NewApp.xcodeproj residing right next to an OldApp source folder. If you attempt to fix this by simply renaming the folders in Finder or Terminal while Xcode is running, the project file loses track of the underlying files, causing source files in the Project Navigator to turn red with missing path errors.

Additionally, several Xcode build settings store hardcoded path strings rather than dynamic macros. Files such as custom Info.plist locations, bridging headers, development asset catalogs, and code signing entitlements often retain references to the old folder structure, triggering file not found errors at build time.

How to fix it

1. Rename the project bundle and targets in Xcode

Before modifying files on disk, let Xcode perform its internal refactoring across targets and configurations.

1. Open your project in Xcode.
2. Ensure your version control working tree is completely clean by committing or stashing all changes.
3. Open the Project Navigator (Cmd + 1) and select the top-level project document.
4. Open the File Inspector in the right-hand utility panel (Cmd + Option + 1).
5. Under the Identity and Type section, click inside the Project Name field, type your new name, and press Return.
6. A modal sheet will appear listing all targets, build configurations, and schemes that can be updated. Click Rename.

Xcode updates the target names and project settings. Check the scheme selector in the toolbar: in modern Xcode versions, your scheme updates automatically. If it does not, click the active scheme, choose Manage Schemes…, click the scheme name to edit it, rename it to your new target name, and click Close.

2. Rename physical source folders and update file references

Once Xcode has adjusted its internal descriptors, update the folder names on your file system.

1. Quit Xcode completely (Cmd + Q).
2. Open Terminal and navigate to your project’s root folder.
3. Use git mv (or Finder if not using Git) to rename the source directory matching your old project name:

git mv OldProjectName NewProjectName

4. If you have an enclosing container folder that also bears the old name, rename it as well.
5. Relaunch Xcode by double-clicking your renamed .xcodeproj or .xcworkspace.
6. Xcode will display a warning that the folder cannot be found, and files in the renamed group will appear in red.
7. In the Project Navigator, select the group representing the folder you just renamed.
8. Open the File Inspector (Cmd + Option + 1). Under Identity and Type, update the Name field to the new folder name.
9. Click the small folder icon next to the Location path string below the name field, navigate to your newly renamed directory on disk, and click Choose.

Xcode will re-index the directory, and all files under that group will instantly resolve and turn back to standard text.

3. Update paths in Build Settings

Some build configuration settings retain hardcoded file paths that point to the old directory structure. You must update these manually.

1. In the Project Navigator, select the project and choose your main target under Targets.
2. Select the Build Settings tab and ensure All and Combined are selected at the top.
3. Search for plist. If Info.plist File contains a hardcoded path like OldProjectName/Info.plist, update it to NewProjectName/Info.plist.
4. Search for Entitlements. If your project uses Code Signing Entitlements, update the path to point to the new location, and rename the .entitlements file in the Project Navigator if desired.
5. If building a SwiftUI app, search for Development Assets and verify that the path to Preview Content points to NewProjectName/Preview Content.
6. If using Objective-C bridging headers, search for Objective-C Bridging Header and update the directory prefix from OldProjectName/ to NewProjectName/.

4. Rename test targets and Core Data models

If your project includes unit test or UI test bundles, repeat the file-system rename process for those folders.

1. Quit Xcode.
2. In Terminal, rename the test directories using Git:

git mv OldProjectNameTests NewProjectNameTests
git mv OldProjectNameUITests NewProjectNameUITests

3. Reopen Xcode, select the test groups in the Project Navigator, and update their folder associations in the File Inspector via the Location icon.
4. In Build Settings for each test target, verify that the Info.plist File path points to NewProjectNameTests/Info.plist.
5. If your project contains a Core Data model named OldProjectName.xcdatamodeld, select it in the Project Navigator, press Return, rename it to NewProjectName.xcdatamodeld, and ensure your persistent container code initializes using the new container name:

let container = NSPersistentContainer(name: "NewProjectName")

5. Update CocoaPods dependencies (if applicable)

If your project relies on CocoaPods, your workspace and Podfile must be synchronized with the new target names.

1. Quit Xcode.
2. In the root directory, rename the .xcworkspace file:

mv OldProjectName.xcworkspace NewProjectName.xcworkspace

3. Open your Podfile in a text editor and update the target declarations to match the renamed Xcode targets:

target 'NewProjectName' do
  use_frameworks!
  pod 'Alamofire'

  target 'NewProjectNameTests' do
    inherit! :search_paths
  end
end

4. Remove the old Pods directory and reinstall dependencies:

rm -rf Pods/
pod install

5. Open NewProjectName.xcworkspace in Xcode.
6. Select your target, switch to Build Phases, expand Link Binary With Libraries, and remove any stale references to libPods-OldProjectName.a if present.
7. Press Cmd + Shift + K to clean the build folder, then press Cmd + B to verify that the project compiles cleanly.

How to prevent it

• Use $(PRODUCT_NAME) and $(TARGET_NAME) macros in your Build Settings instead of typing hardcoded directory paths.
• Avoid using generic or temporary project names during initial prototyping if you plan to keep the code repository.
• Always commit or stash your working directory in Git before executing project-wide renaming operations so you can reset via git reset --hard if references break.
• Rely on Swift Package Manager instead of legacy dependency managers where possible, as SPM packages bind directly to targets without requiring workspace renames.

FAQ

Why do my Swift files show up in red after renaming the folder?

Files turn red when Xcode cannot locate them at the path stored in the .pbxproj file. Select the parent group in the Project Navigator, open the File Inspector, and click the folder icon under Location to point Xcode to the new directory.

Does renaming the Xcode project change the App Store Bundle Identifier?

Not necessarily. If your PRODUCT_BUNDLE_IDENTIFIER build setting uses $(PRODUCT_NAME) or $(TARGET_NAME), it will change automatically; if it is set to a static reverse-DNS string (such as com.example.oldname), you must update it manually in the target’s Signing & Capabilities tab.

Do I need to delete DerivedData after renaming?

Yes, cleaning your build folder with Cmd + Shift + K or manually deleting ~/Library/Developer/Xcode/DerivedData is recommended. Stale module caches and index files frequently cause build failures immediately after a target or folder rename.