iOS 개발자 필독: Xcodebuild 빌드 중 DerivedData 디스크 병목을 빠르게 찾고 처리하는 방법

새벽 2시, CI 파이프라인에서 경고가 울립니다: 빌드 노드 디스크 여유 2 GB 미만, xcodebuild 즉시 종료. 터미널을 열고 df -h를 확인하면 256 GB SSD가 가득 찼습니다——~/Library/Developer만 180 GB를 차지하고, 그중 DerivedData 디렉터리만 90 GB 이상입니다.

이건 드문 일이 아닙니다. 8개월간 정리 없이 돌아간 M4 Mac Mini에서 DerivedData는 평균 40–100 GB까지 쌓입니다. 시뮬레이터 이미지와 디바이스 심볼까지 합치면 ~/Library/Developer가 150 GB를 넘는 것도 흔합니다. 이 글은 근본 원인 분석 → 빠른 특정 → 분류별 처리 → CI 방지 → 자동화 유지 다섯 단계로 바로 따라 할 수 있는 운영 매뉴얼을 제공합니다.

이 글을 마치면 얻는 것: DerivedData 하위 디렉터리별 실제 용도와 안전성 평가, 한 줄 명령으로 최대 디스크 사용 원인 찾기, CI/로컬 양쪽 정리 스크립트, 디스크 경고가 다시 울리지 않게 하는 자동화 방안입니다.

Quick Answer: 가장 흔한 세 가지 질문

DerivedData에 실제로 무엇이 들어 있나

많은 개발자가 「DerivedData를 지우면 이상한 문제가 풀린다」만 알고, 안에 무엇이 있는지는 모릅니다. 그 결과 지우면 안 되는 것을 지우거나, 지워야 할 것을 남겨 디스크가 반복해서 터집니다. 아래 표는 ~/Library/Developer 아래 가장 중요한 경로입니다.

DerivedData 하위 디렉터리 구조

각 프로젝트는 DerivedData 아래 {프로젝트명}-{랜덤 해시}/ 형식의 독립 하위 디렉터리를 가집니다. 내부 구조는 다음과 같습니다.

MyApp-abcdefghijklmn/
├── Build/
│   ├── Products/          # 빌드 산출물(.app, .framework, .o)
│   └── Intermediates.noindex/  # 중간 파일(.o, .d 의존 그래프)
├── Index.noindex/         # SourceKit 인덱스(코드 점프, 자동 완성)
├── Logs/                  # 빌드 로그(xcodebuild -resultBundlePath도 여기)
└── info.plist             # 프로젝트 경로 기록

그중 Build/Intermediates.noindex가 보통 가장 큽니다——Swift 파일 200개 규모 중형 프로젝트에서 이 디렉터리만 2 GB를 넘기기 쉽고, Index.noindex까지 합치면 단일 프로젝트 DerivedData가 5–10 GB에 달하는 경우가 흔합니다.

다섯 단계로 디스크 병목 원인 빠르게 찾기

처음부터 무차별 정리하지 마세요. 3분 투자해 특정하면 무작정 지우는 것보다 효율적입니다. 아래 절차는 256 GB M4 Mac Mini에서 실측했으며, 2분 안에 상위 5개 디렉터리를 찾을 수 있습니다.

Step 1: 디스크 전체 사용량 확인

# 전체 디스크 사용률 확인
df -h /

# 상위 10개 디렉터리 빠르게 특정(루트 전체)
sudo du -sh /* 2>/dev/null | sort -rh | head -10

Step 2: Developer 디렉터리 세부 분포 확인

du -sh ~/Library/Developer/Xcode/* 2>/dev/null | sort -rh
du -sh ~/Library/Developer/CoreSimulator/Profiles/Runtimes/* 2>/dev/null | sort -rh
du -sh ~/Library/Developer/Xcode/iOS\ DeviceSupport/* 2>/dev/null | sort -rh

실측 출력 예(8개월 돌린 CI 노드):

91G    /Users/ci/Library/Developer/Xcode/DerivedData
28G    /Users/ci/Library/Developer/CoreSimulator
18G    /Users/ci/Library/Developer/Xcode/iOS DeviceSupport
12G    /Users/ci/Library/Developer/Xcode/Archives
 6G    /Users/ci/Library/Developer/Xcode/Caches

Step 3: DerivedData에서 가장 큰 하위 프로젝트 찾기

du -sh ~/Library/Developer/Xcode/DerivedData/* 2>/dev/null | sort -rh | head -10

Step 4: 시뮬레이터 사용량과 상태 확인

# 모든 시뮬레이터 및 상태 나열
xcrun simctl list devices

# "unavailable"만 보기(시스템 업그레이드 후 잔여)
xcrun simctl list devices | grep -i "unavailable"

Step 5: DeviceSupport 버전 분포 확인

ls -lh ~/Library/Developer/Xcode/iOS\ DeviceSupport/

출력이 아래와 같으면 여러 해 동안 쌓인 디바이스 심볼 파일입니다.

drwxr-xr-x  3 dev  staff   96B  iOS 15.4 (19E241)
drwxr-xr-x  3 dev  staff   96B  iOS 16.1 (20B82)
drwxr-xr-x  3 dev  staff   96B  iOS 17.2 (21C62)
drwxr-xr-x  3 dev  staff   96B  iOS 18.3.2 (22D82)

2026년 기준 iOS 15·16 심볼은 거의 보관 가치가 없습니다(App Store 최소 버전 요구가 대체로 iOS 17 이상). 안심하고 삭제해도 됩니다.

디렉터리별 처리 전략: 삭제 가능, 신중, 불가

바로 삭제 가능(위험 없음)

# 1. 모든 프로젝트 빌드 캐시 비우기
rm -rf ~/Library/Developer/Xcode/DerivedData/*

# 2. unavailable 시뮬레이터 삭제
xcrun simctl delete unavailable

# 3. SPM 패키지 캐시 정리
rm -rf ~/Library/Caches/org.swift.swiftpm/*

# 4. Xcode 내부 캐시 정리
rm -rf ~/Library/Caches/com.apple.dt.Xcode/*

# 5. SwiftUI 미리보기 캐시 정리
rm -rf ~/Library/Developer/Xcode/UserData/Previews/*

선택적 삭제(오래된 것만 지우고 최신 유지)

# 2버전 이전 디바이스 심볼 삭제(최신 두 iOS 버전만 유지)
# 먼저 현재 버전 확인
ls ~/Library/Developer/Xcode/iOS\ DeviceSupport/

# 예: iOS 18.x만 남기고 이전 버전 삭제
rm -rf ~/Library/Developer/Xcode/iOS\ DeviceSupport/iOS\ 15*
rm -rf ~/Library/Developer/Xcode/iOS\ DeviceSupport/iOS\ 16*
rm -rf ~/Library/Developer/Xcode/iOS\ DeviceSupport/iOS\ 17*

신중히 다룰 것: Archives

• 해당 버전이 App Store에서 내려갔거나 활성 사용자가 없는지 확인
• 여전히 사용자가 있다면 dSYM을 별도로 보내기(Organizer → Archive 우클릭 → Show in Finder → .dSYM 추출)
• dSYM을 Firebase Crashlytics / Sentry 등 크래시 분석 플랫폼에 업로드
• 플랫폼이 dSYM을 수신한 뒤 해당 Archive 삭제

원클릭 응급 명령(디스크 위기 시)

아래 명령을 안전한 순서로 실행하면 보통 20–60 GB를 빠르게 확보할 수 있습니다.

#!/bin/bash
# emergency-clean-xcode.sh
# 실행 전 확인: 실행 중인 xcodebuild 프로세스 없음
echo "=== Xcode 디스크 긴급 정리 ==="

echo "[1/4] DerivedData 정리..."
du -sh ~/Library/Developer/Xcode/DerivedData 2>/dev/null
rm -rf ~/Library/Developer/Xcode/DerivedData/*
echo "✓ DerivedData 비움"

echo "[2/4] unavailable 시뮬레이터 삭제..."
xcrun simctl delete unavailable
echo "✓ unavailable 시뮬레이터 삭제됨"

echo "[3/4] SPM 및 Xcode 캐시 정리..."
rm -rf ~/Library/Caches/org.swift.swiftpm/*
rm -rf ~/Library/Caches/com.apple.dt.Xcode/*
echo "✓ 캐시 정리됨"

echo "[4/4] 미리보기 캐시 정리..."
rm -rf ~/Library/Developer/Xcode/UserData/Previews/*
echo "✓ 미리보기 캐시 정리됨"

echo ""
echo "=== 정리 완료, 현재 디스크 상태 ==="
df -h /

CI/CD 파이프라인 디스크 병목 방지

로컬 개발 머신은 수동 정리로 버틸 수 있지만, CI Runner는 무인 운영이므로 체계적 방어가 필요합니다. 자체 호스팅 macOS Runner(GitHub Actions / GitLab CI) 기준으로 세 가지 방안을 제시합니다.

방안 A: DerivedData 경로 고정 + 증분 캐시

DerivedData를 제어 가능한 경로로 지정하고 CI 캐시로 Job 간 재사용합니다.

# .github/workflows/ios-build.yml 일부
- name: Build
  run: |
    xcodebuild \
      -project MyApp.xcodeproj \
      -scheme MyApp \
      -configuration Release \
      -derivedDataPath /tmp/derived-data \
      -resultBundlePath /tmp/result.xcresult \
      build

- name: Cache DerivedData
  uses: actions/cache@v4
  with:
    path: /tmp/derived-data
    key: derived-data-${{ runner.os }}-${{ hashFiles('**/Package.resolved') }}-${{ hashFiles('**/*.xcodeproj/project.pbxproj') }}
    restore-keys: |
      derived-data-${{ runner.os }}-

방안 B: 빌드 전후 오래된 캐시 자동 정리

# 빌드 단계 전: 7일 이상 미사용 DerivedData 하위 디렉터리 정리
- name: Clean stale DerivedData
  run: |
    find ~/Library/Developer/Xcode/DerivedData \
      -maxdepth 1 -mindepth 1 \
      -type d \
      -atime +7 \
      -exec rm -rf {} +
    echo "DerivedData 정리 완료, 현재 크기:"
    du -sh ~/Library/Developer/Xcode/DerivedData 2>/dev/null || echo "디렉터리 비어 있음"

방안 C: GitLab CI 디스크 용량 게이트

.gitlab-ci.yml에 사전 검사 Job을 추가해 디스크 부족 시 fail-fast로 중간에 깨지는 무효 빌드를 막습니다.

# .gitlab-ci.yml
check_disk:
  stage: .pre
  script:
    - |
      AVAIL=$(df -k / | awk 'NR==2 {print $4}')
      THRESHOLD=$((10 * 1024 * 1024))  # 10 GB in KB
      if [ "$AVAIL" -lt "$THRESHOLD" ]; then
        echo "ERROR: 디스크 여유 10 GB 미만(현재: $((AVAIL/1024/1024)) GB), 먼저 정리하세요"
        exit 1
      fi
      echo "디스크 검사 통과, 여유: $((AVAIL/1024/1024)) GB"
  tags:
    - macos-runner

세 방안 비교

세 방안을 겹쳐 쓰는 것을 권장합니다: A로 빌드 속도, B로 디스크 증가 억제, C로 마지막 방어.

자동화 유지: 정기 스크립트 + 용량 경고

수동 정리는 결국 놓치기 쉽습니다. 정리 로직을 스크립트로 만들고 macOS launchd에 걸면 디스크 문제를 수동 대응에서 능동 방어로 바꿀 수 있습니다.

전체 유지보수 스크립트

#!/bin/bash
# xcode-maintenance.sh
# 매주 일요일 새벽 3시 실행 권장
# 경로: ~/scripts/xcode-maintenance.sh

LOGFILE=~/Library/Logs/xcode-maintenance.log
THRESHOLD_GB=20  # 여유 디스크가 이 값 미만이면 심층 정리

log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOGFILE"; }

log "=== Xcode 정기 유지보수 시작 ==="

# 1. 정리 전 디스크 상태 기록
BEFORE=$(df -h / | awk 'NR==2 {print $4}')
log "정리 전 디스크 가용: $BEFORE"

# 2. 14일 미접근 DerivedData 하위 디렉터리 삭제
log "14일 이상 미사용 DerivedData 정리..."
find ~/Library/Developer/Xcode/DerivedData \
  -maxdepth 1 -mindepth 1 -type d -atime +14 \
  -exec rm -rf {} + 2>/dev/null
log "✓ DerivedData 오래된 항목 정리됨"

# 3. unavailable 시뮬레이터 삭제
log "unavailable 시뮬레이터 정리..."
xcrun simctl delete unavailable 2>/dev/null
log "✓ unavailable 시뮬레이터 삭제됨"

# 4. SPM 캐시 정리(30일 초과)
find ~/Library/Caches/org.swift.swiftpm -maxdepth 2 \
  -type f -atime +30 -delete 2>/dev/null
log "✓ 오래된 SPM 캐시 정리됨"

# 5. 여유 공간이 임계값 미만이면 심층 정리
AVAIL_GB=$(df -g / | awk 'NR==2 {print $4}')
if [ "$AVAIL_GB" -lt "$THRESHOLD_GB" ]; then
  log "⚠️  디스크 여유 ${AVAIL_GB}GB < ${THRESHOLD_GB}GB, 심층 정리 실행"
  rm -rf ~/Library/Developer/Xcode/DerivedData/*
  rm -rf ~/Library/Caches/com.apple.dt.Xcode/*
  rm -rf ~/Library/Developer/Xcode/UserData/Previews/*
  log "✓ 심층 정리 완료"
fi

AFTER=$(df -h / | awk 'NR==2 {print $4}')
log "정리 후 디스크 가용: $AFTER"
log "=== 유지보수 완료 ==="

launchd 정기 작업으로 등록

매주 일요일 새벽 3시에 자동 실행되도록 등록합니다.

# 1. 실행 권한 부여
chmod +x ~/scripts/xcode-maintenance.sh

# 2. launchd plist 생성
cat > ~/Library/LaunchAgents/com.myteam.xcode-maintenance.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.myteam.xcode-maintenance</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>/Users/YOUR_USER/scripts/xcode-maintenance.sh</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Weekday</key><integer>0</integer>
    <key>Hour</key><integer>3</integer>
    <key>Minute</key><integer>0</integer>
  </dict>
  <key>StandardOutPath</key>
  <string>/tmp/xcode-maintenance-stdout.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/xcode-maintenance-stderr.log</string>
</dict>
</plist>
EOF

# 3. 로드
launchctl load ~/Library/LaunchAgents/com.myteam.xcode-maintenance.plist
echo "정기 작업 등록됨"

클라우드 Mac으로 디스크 문제를 근본적으로 피하는 방법

위 방안은 모두 「제한된 디스크」 전제에서 완화하는 것입니다. CI 인프라를 검토 중이라면 로컬 노드를 클라우드 전용 Mac Mini로 대체하는 선택을 진지히 고려할 가치가 있습니다.

클라우드 아키텍처에서는 디스크 관리가 다른 경로로 풀립니다.

• 확장 SSD 추가: Macstripe M4 Mac Mini는 스토리지 확장을 지원해, 수동 정리보다 큰 디스크를 사는 편이 훨씬 수월합니다
• 주기적 노드 리셋: 월 단위 노드는 주기 종료 후 깨끗한 머신을 다시 개통해 DerivedData를 0부터 시작——정리 스크립트 불필요
• 필요 시 확장: 릴리스 집중기에 노드를 늘려 빌드 부하를 나누고, 한산할 때 줄여 피크 용량에 장기 과금하지 않음
• SSH 직접 디버깅: 노드에서 빌드 이슈가 생기면 ssh runner@your-node로 바로 접속해 물리 머신 원격 관리보다 편하게 진단

실제 사례: 한 모바일 팀이 로컬 Mac Mini 3대를 Macstripe 클라우드 노드로 바꾼 뒤, 월 디스크 정리·Xcode 업데이트·Runner 장애 대응에 쓰던 시간이 약 8–12시간 줄었습니다. 엔지니어 시급으로 환산하면 임대 비용의 상당 부분을 운영 비용 절감만으로 상쇄했습니다.

이미 GitHub Actions 워크플로가 있다면 Windows만으로 iOS 개발? Mac 안 사도 될까? 글도 참고해 다양한 플랫폼에서 iOS 앱을 빌드할 때의 전체 비교를 확인하세요.

FAQ

Q: DerivedData를 바로 삭제하면 소스나 릴리스 기록에 영향이 있나요?

없습니다. DerivedData에는 빌드 산출물, SourceKit 인덱스, 빌드 로그만 있으며 소스·Git 기록·Provisioning Profile·App Store Connect 제출과 완전히 분리됩니다. 삭제 후 Xcode가 다음 빌드에서 전체 재생성하며, 유일한 비용은 전체 빌드로 인한 중형 프로젝트 기준 약 2–5분 추가입니다.

Q: Archives 디렉터리는 아무 때나 삭제해도 되나요?

무작정 삭제하면 안 됩니다. Archives의 .xcarchive에는 dSYM 심볼이 있어 프로덕션 크래시 로그 심볼화에 쓰입니다. 삭제 전 ① App Store에서 내려갔고 활성 사용자가 없거나 ② dSYM을 Firebase Crashlytics / Sentry 등에 업로드했는지 확인하세요. 최근 3개 릴리스 Archive는 보관하고, 그 이전은 dSYM 보낸 뒤 삭제하는 것을 권장합니다.

Q: CI에서 매번 전체 재빌드하는데 캐시를 재사용할 수 있나요?

가능합니다. -derivedDataPath /tmp/derived-data를 xcodebuild에 넘기고 GitHub Actions actions/cache 또는 GitLab CI cache:로 증분 동기화하세요. Cache key에 Package.resolved와 project.pbxproj 해시를 넣어 의존성 버전 간 오염을 막으세요. Swift Package가 많은 프로젝트에서 증분 빌드는 실측 40–60% 시간 절약이 가능합니다.

Q: 디스크 부족으로 xcodebuild가 바로 실패할 때 빠르게 복구하려면?

우선순위대로: ① rm -rf ~/Library/Developer/Xcode/DerivedData/*(보통 10–60 GB 확보); ② xcrun simctl delete unavailable(5–20 GB); ③ 두 버전 이상 된 iOS DeviceSupport 항목 삭제(5–15 GB). 대부분 ①만으로 해결됩니다.

Q: Xcode 「Product > Clean Build Folder」와 명령줄 DerivedData 삭제의 차이는?

Clean Build Folder는 현재 열린 프로젝트 빌드 산출물만 정리합니다. 다른 프로젝트 캐시·시뮬레이터·DeviceSupport에는 영향이 없습니다. 명령줄 rm -rf ~/Library/Developer/Xcode/DerivedData/*는 모든 프로젝트 캐시를 지웁니다. CI 노드 유지에는 명령줄, 개발 머신 일상에는 Clean Build Folder가 더 정밀합니다.

Q: CI Runner에서 DerivedData가 특히 빠르게 늘어날 때는?

원인은 보통 여러 Scheme/브랜치가 동시에 빌드되며 매번 새 DerivedData 하위 디렉터리가 생기는 것입니다. ① -derivedDataPath로 단일 경로 고정; ② 빌드 스크립트에 find ... -atime +7 -exec rm -rf {} +로 7일 미접근 항목 정리; ③ 노드 디스크 확장 또는 Macstripe 클라우드 Mac 확장 SSD 옵션 검토를 권장합니다.

요약

DerivedData 디스크 병목은 iOS 개발자가 거의 반드시 겪는 문제지만, 체계적으로 해결할 수 있으며 매번 「이상 현상」 때마다 급히 지울 필요는 없습니다.

• 근본 이해: DerivedData는 순수 캐시로 안전 삭제 가능; Archives는 dSYM 포함으로 신중히
• 빠른 진단: du -sh ~/Library/Developer/Xcode/* | sort -rh 한 줄로 원인 특정
• 분류 처리: DerivedData는 과감히, DeviceSupport는 오래된 것만, Archives는 dSYM 보낸 뒤
• CI 방어: -derivedDataPath 고정 + 증분 캐시 + 용량 게이트 3중 보호
• 자동화: launchd에 유지 스크립트를 걸어 주간 자동 정리, 수동 대응에서 능동 방어로
• 근본 해결: 클라우드 Mac으로 확장 SSD 또는 주기 리셋으로 디스크 불안 종료

팀이 CI 노드 디스크 경고와 빌드 중단에 시달린다면, 먼저 글의 진단 스크립트를 한 번 돌려보세요. 보통 10분 안에 30 GB 이상 확보할 수 있습니다. 장기적으로는 CI 인프라를 클라우드 전용 Mac Mini로 옮기는 것이 더 지속 가능합니다——필요 시 확장하고 디스크 유지 부담 없이 운영할 수 있습니다.

관련 글

• Windows만으로 iOS 개발? Mac 안 사도 될까?
• Apple Intelligence, 돈 내고 쓸 만한가? 기능·가격·구독 완전 분석 (2026)