349 일반적인 설치 문제349 일반적인 설치 문제
350</h2>350</h2>
351 351
352이는 가장 자주 발생하는 설치 문제와 해결책입니다.352가장 자주 발생하는 설치 문제와 해결 방법입니다.
353 353
354<h3 id="install-script-returns-html-instead-of-a-shell-script">354<h3 id="install-script-returns-html-instead-of-a-shell-script">
355 설치 스크립트가 셸 스크립트 대신 HTML 반환355 설치 스크립트가 셸 스크립트 대신 HTML을 반환합니다
356</h3>356</h3>
357 357
358설치 명령을 실행할 때 다음 오류 중 하나가 표시될 수 있습니다:358설치 명령을 실행할 때 다음 오류 중 하나가 표시될 수 있습니다.
359 359
360```text theme={null}360```text theme={null}
361bash: line 1: syntax error near unexpected token `<'361bash: line 1: syntax error near unexpected token `<'
362bash: line 1: `<!DOCTYPE html>'362bash: line 1: `<!DOCTYPE html>'
363```363```
364 364
365PowerShell에서 동일한 문제는 반환된 페이지로 파싱 오류로 나타나며, `iex`가 HTML과 CSS를 PowerShell로 실행하려고 시도합니다:365PowerShell에서는 동일한 문제가 반환된 페이지를 가리키는 구문 분석 오류로 나타나며, `iex`가 HTML과 CSS를 PowerShell로 실행하려고 시도합니다.
366 366
367```text theme={null}367```text theme={null}
368iex : At line:1 char:2310368iex : At line:1 char:2310
371...371...
372```372```
373 373
374표현은 PowerShell 버전 및 시스템 언어에 따라 다릅니다: `Missing expression after unary operator '--'` 또는 `ParserError`와 함께 `ParseException`이 표시될 수 있습니다. 인용된 텍스트의 HTML 태그 또는 CSS는 이 실패를 식별합니다. 대신 `-OutFile install.ps1`로 다운로드하면 저장된 파일은 동일한 웹 페이지이므로 도움이 되지 않습니다.374표현은 PowerShell 버전과 시스템 언어에 따라 다릅니다. `Missing expression after unary operator '--'` 또는 `ParserError`와 함께 `ParseException`이 표시될 수 있습니다. 인용된 텍스트의 HTML 태그 또는 CSS는 이 오류를 식별합니다. `-OutFile install.ps1`로 다운로드하면 저장된 파일도 동일한 웹 페이지이므로 도움이 되지 않습니다.
375 375
376요청이 라우팅된 방식에 따라 HTML 본문이 없는 403이 대신 표시될 수 있습니다:376요청이 라우팅된 방식에 따라 HTML 본문이 없는 403이 표시될 수 있습니다.
377 377
378```text theme={null}378```text theme={null}
379curl: (22) The requested URL returned error: 403379curl: (22) The requested URL returned error: 403
380```380```
381 381
382이 모든 것은 설치 URL이 설치 스크립트 대신 HTML 페이지 또는 오류 상태를 반환했음을 의미합니다. HTML 페이지에 "App unavailable in region"이 표시되면 Claude Code는 귀국에서 사용할 수 없습니다. [지원되는 국가](https://www.anthropic.com/supported-countries)를 참조하세요.382이 모든 경우는 설치 URL이 설치 스크립트 대신 HTML 페이지 또는 오류 상태를 반환했음을 의미합니다. HTML 페이지에 "App unavailable in region"이라고 표시되면 Claude Code를 사용할 수 없는 국가입니다. [지원되는 국가](https://www.anthropic.com/supported-countries)를 참조하세요.
383 383
384본문이 없는 단순 403은 종종 동일한 원인을 가지지만 회사 프록시 또는 방화벽이 다운로드를 차단하는 것에서 비롯될 수도 있습니다. 지원되는 국가에 있는데도 여전히 403이 표시되면 아래의 대체 설치 프로그램을 시도하기 전에 [네트워크 연결 확인](#check-network-connectivity)을 진행하세요. 대체 설치 프로그램도 동일한 호스트에 도달하기 때문입니다.384본문이 없는 단순 403은 동일한 원인을 가질 수 있지만 회사 프록시 또는 방화벽이 다운로드를 차단할 수도 있습니다. 지원되는 국가에 있는데도 403이 표시되면 아래의 대체 설치 프로그램을 시도하기 전에 [네트워크 연결 확인](#check-network-connectivity)을 진행하세요. 대체 설치 프로그램도 동일한 호스트에 도달하기 때문입니다.
385 385
386그렇지 않으면 네트워크 문제, 지역 라우팅 또는 일시적인 서비스 중단으로 인해 발생할 수 있습니다.386그 외에는 네트워크 문제, 지역 라우팅 또는 일시적인 서비스 중단으로 인해 발생할 수 있습니다.
387 387
388**해결책:**388**해결 방법:**
389 389
3901. **대체 설치 방법 사용**:3901. **대체 설치 방법 사용**:
391 391
392 macOS에서 Homebrew를 통해 설치:392 macOS에서는 Homebrew를 통해 설치합니다.
393 393
394 ```bash theme={null}394 ```bash theme={null}
395 brew install --cask claude-code395 brew install --cask claude-code
396 ```396 ```
397 397
398 Windows에서 WinGet을 통해 설치:398 Windows에서는 WinGet을 통해 설치합니다.
399 399
400 ```powershell theme={null}400 ```powershell theme={null}
401 winget install Anthropic.ClaudeCode401 winget install Anthropic.ClaudeCode
402 ```402 ```
403 403
404 그런 다음 `claude --version`을 실행하여 확인하세요: 명령은 `2.1.211 (Claude Code)`와 같은 버전 번호를 인쇄합니다. 셸이 `claude`를 찾을 수 없다고 보고하면 새 터미널 창을 열고 다시 시도하세요: 설치한 세션은 이전 `PATH`를 유지합니다.404 그런 다음 `claude --version`을 실행하여 확인합니다. 명령은 `2.1.211 (Claude Code)`와 같은 버전 번호를 출력합니다. 셸에서 `claude`를 찾을 수 없다고 보고하면 새 터미널 창을 열고 다시 시도합니다. 설치한 세션은 이전 `PATH`를 유지합니다.
405 405
4062. **몇 분 후 다시 시도**: 문제는 종종 일시적입니다. 기다렸다가 원래 명령을 다시 시도하세요.4062. **몇 분 후 다시 시도합니다**: 이 문제는 종종 일시적입니다. 기다렸다가 원래 명령을 다시 시도합니다.
407 407
408<h3 id="command-not-found-claude-after-installation">408<h3 id="command-not-found-claude-after-installation">
409 설치 후 `command not found: claude`409 설치 후 `command not found: claude`
410</h3>410</h3>
411 411
412설치가 완료되었지만 `claude`가 작동하지 않습니다. 정확한 오류는 플랫폼에 따라 다릅니다:412설치가 완료되었지만 `claude`가 작동하지 않습니다. 정확한 오류는 플랫폼에 따라 다릅니다.
413 413
414| 플랫폼 | 오류 메시지 |414| 플랫폼 | 오류 메시지 |
415| :- | :- |415| :- | :- |
418| Windows CMD | `'claude' is not recognized as an internal or external command` |418| Windows CMD | `'claude' is not recognized as an internal or external command` |
419| PowerShell | `claude : The term 'claude' is not recognized as the name of a cmdlet` |419| PowerShell | `claude : The term 'claude' is not recognized as the name of a cmdlet` |
420 420
421이는 설치 디렉토리가 셸의 검색 경로에 없음을 의미합니다. 각 플랫폼의 수정 사항은 [PATH 확인](#verify-your-path)을 참조하세요.421이는 설치 디렉토리가 셸의 검색 경로에 없음을 의미합니다. 각 플랫폼의 수정 방법은 [PATH 확인](#verify-your-path)을 참조하세요.
422 422
423<h3 id="curl-56-failure-writing-output-to-destination">423<h3 id="curl-56-failure-writing-output-to-destination">
424 `curl: (56) Failure writing output to destination`424 `curl: (56) Failure writing output to destination`
425</h3>425</h3>
426 426
427`curl ... | bash` 명령은 스크립트를 다운로드하고 Bash에 파이프하여 실행합니다. 이 오류와 관련된 `curl: (23) Failure writing output to destination`은 Bash가 완전한 스크립트를 받지 못했음을 의미합니다. 종료 코드 56은 다운로드 자체가 중단되었음을 나타내고 종료 코드 23은 curl이 받은 것을 파이프에 쓸 수 없었음을 나타내며, 일반적으로 Bash가 조기에 종료되었기 때문입니다.427`curl ... | bash` 명령은 스크립트를 다운로드하고 Bash로 실행하기 위해 파이프합니다. 이 오류와 관련된 `curl: (23) Failure writing output to destination`은 Bash가 완전한 스크립트를 받지 못했음을 의미합니다. 종료 코드 56은 다운로드 자체가 중단되었음을 나타내고, 종료 코드 23은 curl이 받은 내용을 파이프에 쓸 수 없었음을 나타냅니다. 보통 Bash가 조기에 종료되었기 때문입니다.
428 428
429[네트워크 연결 확인](#check-network-connectivity)의 확인으로 `downloads.claude.ai`에 도달할 수 있는지 테스트하세요. 서버에 도달했으면 원래 실패는 일시적이었을 가능성이 높습니다. 설치 명령을 다시 시도하세요. [대체 설치 방법](/docs/ko/setup#install-claude-code)을 시도할 수도 있습니다.429[네트워크 연결 확인](#check-network-connectivity)의 확인으로 `downloads.claude.ai`에 도달할 수 있는지 테스트합니다. 서버에 도달했다면 원래 오류는 일시적일 가능성이 높습니다. 설치 명령을 다시 시도합니다. [대체 설치 방법](/docs/ko/setup#install-claude-code)을 시도할 수도 있습니다.
430 430
431<h3 id="homebrew-cask-unavailable-or-outdated">431<h3 id="homebrew-cask-unavailable-or-outdated">
432 Homebrew cask를 사용할 수 없거나 오래됨432 Homebrew cask를 사용할 수 없거나 오래되었습니다
433</h3>433</h3>
434 434
435Homebrew가 `Error: Cask 'claude-code' is unavailable: No Cask with this name exists`를 보고하면 Homebrew cask 인덱스의 로컬 복사본이 cask의 게시 이전입니다. 인덱스를 새로 고치고 다시 시도하세요:435Homebrew가 `Error: Cask 'claude-code' is unavailable: No Cask with this name exists`를 보고하면 Homebrew cask 인덱스의 로컬 복사본이 cask의 게시 이전입니다. 인덱스를 새로 고치고 다시 시도합니다.
436 436
437```bash theme={null}437```bash theme={null}
438brew update438brew update
439brew install --cask claude-code439brew install --cask claude-code
440```440```
441 441
442Homebrew가 예상보다 이전 Claude Code 버전을 설치하면 동일한 오래된 인덱스가 일반적으로 원인입니다. `claude-code` cask는 안정적인 채널을 추적하며 일반적으로 최신 릴리스보다 약 1주일 뒤떨어져 있습니다. 최신 버전의 경우 대신 `brew install --cask claude-code@latest`를 실행하세요. 두 cask의 차이점은 [릴리스 채널 구성](/docs/ko/setup#configure-release-channel)을 참조하세요.442Homebrew가 예상보다 오래된 Claude Code 버전을 설치하면 동일한 오래된 인덱스가 보통 원인입니다. `claude-code` cask는 안정 채널을 추적하며 보통 최신 릴리스보다 약 1주일 뒤떨어져 있습니다. 최신 버전을 원하면 `brew install --cask claude-code@latest`를 대신 실행합니다. 두 cask의 차이점은 [릴리스 채널 구성](/docs/ko/setup#configure-release-channel)을 참조하세요.
443 443
444<h3 id="tls-or-ssl-connection-errors">444<h3 id="tls-or-ssl-connection-errors">
445 TLS 또는 SSL 연결 오류445 TLS 또는 SSL 연결 오류
446</h3>446</h3>
447 447
448`curl: (35) TLS connect error`, `schannel: next InitializeSecurityContext failed` 또는 PowerShell의 `Could not establish trust relationship for the SSL/TLS secure channel`과 같은 오류는 TLS 핸드셰이크 실패를 나타냅니다.448다음과 같은 오류는 TLS 핸드셰이크가 실패했음을 의미합니다.
449 449
450**해결책:**450* `curl: (35) TLS connect error`
451* `schannel: next InitializeSecurityContext failed`
452* PowerShell의 `Could not create SSL/TLS secure channel`
453* PowerShell의 `Could not establish trust relationship for the SSL/TLS secure channel`
454
455**해결 방법:**
451 456
4521. **시스템 CA 인증서 업데이트**:4571. **시스템 CA 인증서 업데이트**:
453 458
457 sudo apt-get update && sudo apt-get install ca-certificates462 sudo apt-get update && sudo apt-get install ca-certificates
458 ```463 ```
459 464
460 macOS에서 시스템 curl은 Keychain 신뢰 저장소를 사용합니다. macOS 자체를 업데이트하면 루트 인증서가 업데이트됩니다.465 macOS에서는 시스템 curl이 Keychain 신뢰 저장소를 사용합니다. macOS 자체를 업데이트하면 루트 인증서가 업데이트됩니다.
461 466
4622. **Windows에서 설치 프로그램을 실행하기 전에 PowerShell에서 TLS 1.2 활성화**:4672. **Windows에서 설치 프로그램을 실행하기 전에 PowerShell에서 TLS 1.2 활성화**:
463 ```powershell theme={null}468 ```powershell theme={null}
465 irm https://claude.ai/install.ps1 | iex470 irm https://claude.ai/install.ps1 | iex
466 ```471 ```
467 472
4683. **프록시 또는 방화벽 간섭 확인**: TLS 검사를 수행하는 회사 프록시는 `unable to get local issuer certificate` 및 `SELF_SIGNED_CERT_IN_CHAIN`을 포함한 이러한 오류를 유발할 수 있습니다. 설치 단계의 경우 설치 다운로드가 회사 프록시의 CA를 신뢰하도록 하세요:4733. **프록시 또는 방화벽 간섭 확인**: TLS 검사를 수행하는 회사 프록시는 `unable to get local issuer certificate` 및 `SELF_SIGNED_CERT_IN_CHAIN`을 포함한 이러한 오류를 유발할 수 있습니다. 설치 단계의 경우 설치 다운로드가 회사 프록시의 CA를 신뢰하도록 합니다.
469 474
470 <Tabs>475 <Tabs>
471 <Tab title="macOS/Linux">476 <Tab title="macOS/Linux">
475 </Tab>480 </Tab>
476 481
477 <Tab title="Windows PowerShell">482 <Tab title="Windows PowerShell">
478 PowerShell 설치 프로그램은 .NET을 통해 다운로드하며, 이는 Windows 인증서 저장소에 대해 TLS를 검증합니다. IT 팀에 프록시의 CA 인증서를 Windows 저장소에 추가하도록 요청하세요(아직 없는 경우). 그런 다음 설치 프로그램을 실행하세요:483 PowerShell 설치 프로그램은 .NET을 통해 다운로드하며, Windows 인증서 저장소에 대해 TLS를 검증합니다. IT 팀에 프록시의 CA 인증서를 Windows 저장소에 추가하도록 요청합니다(아직 없는 경우). 그런 다음 설치 프로그램을 실행합니다.
479 484
480 ```powershell theme={null}485 ```powershell theme={null}
481 irm https://claude.ai/install.ps1 | iex486 irm https://claude.ai/install.ps1 | iex
483 </Tab>488 </Tab>
484 </Tabs>489 </Tabs>
485 490
486 설치된 Claude Code 자체의 경우 `NODE_EXTRA_CA_CERTS`를 설정하여 API 요청이 동일한 번들을 신뢰하도록 하세요:491 설치된 Claude Code 자체의 경우 `NODE_EXTRA_CA_CERTS`를 설정하여 API 요청이 동일한 번들을 신뢰하도록 합니다.
487 492
488 <Tabs>493 <Tabs>
489 <Tab title="macOS/Linux">494 <Tab title="macOS/Linux">
499 </Tab>504 </Tab>
500 </Tabs>505 </Tabs>
501 506
502 인증서 파일이 없으면 IT 팀에 문의하세요. 프록시가 원인인지 확인하기 위해 직접 연결에서 시도할 수도 있습니다.507 인증서 파일이 없으면 IT 팀에 요청합니다. 프록시가 원인인지 확인하기 위해 직접 연결에서 시도할 수도 있습니다.
503 508
5044. **Windows에서 차단된 해지 확인 해결**. `CRYPT_E_NO_REVOCATION_CHECK (0x80092012)` 및 `CRYPT_E_REVOCATION_OFFLINE (0x80092013)` 오류는 curl이 서버에 도달했지만 네트워크가 인증서 해지 조회를 차단함을 의미하며, 이는 회사 방화벽 뒤에서 일반적입니다. 실패한 명령이 `install.cmd`를 다운로드하는 `curl`인 경우 `--ssl-revoke-best-effort`를 추가하여 명령 프롬프트에서 다시 실행하세요:5094. **Windows에서 차단된 해지 확인 해결**. 오류 `CRYPT_E_NO_REVOCATION_CHECK (0x80092012)` 및 `CRYPT_E_REVOCATION_OFFLINE (0x80092013)`은 curl이 서버에 도달했지만 네트워크가 인증서 해지 조회를 차단함을 의미합니다. 이는 회사 방화벽 뒤에서 일반적입니다. 실패한 명령이 `install.cmd`를 다운로드하는 `curl`인 경우 `--ssl-revoke-best-effort`를 추가하여 명령 프롬프트에서 다시 실행합니다.
505 ```batch theme={null}510 ```batch theme={null}
506 curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd511 curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
507 ```512 ```
508 스크립트 자체의 다운로드가 동일한 오류를 겪으면 자동으로 최선의 노력 해지 확인으로 다시 시도하므로 플래그는 직접 실행하는 명령에만 필요합니다. 최선의 노력 확인은 도달할 수 없는 해지 서버를 허용하지만 알려진 해지된 인증서는 거부하며, 브라우저가 해지를 처리하는 방식과 일치합니다. PowerShell에서 PowerShell 설치 프로그램을 실행하여 curl의 해지 확인을 완전히 피할 수도 있습니다. 이는 .NET을 통해 다운로드하며 해지 서버에 도달할 수 없을 때 실패하지 않습니다:513 스크립트 자체의 다운로드가 동일한 오류에 직면하면 자동으로 최선의 노력 해지 확인으로 다시 시도하므로 플래그는 직접 실행하는 명령에만 필요합니다. 최선의 노력 확인은 도달할 수 없는 해지 서버를 허용하지만 알려진 해지된 인증서는 거부하며, 브라우저가 해지를 처리하는 방식과 일치합니다. PowerShell에서 PowerShell 설치 프로그램을 실행하여 curl의 해지 확인을 완전히 피할 수도 있습니다. PowerShell 설치 프로그램은 .NET을 통해 다운로드하며 해지 서버에 도달할 수 없을 때 실패하지 않습니다.
509 ```powershell theme={null}514 ```powershell theme={null}
510 irm https://claude.ai/install.ps1 | iex515 irm https://claude.ai/install.ps1 | iex
511 ```516 ```
515 `Failed to fetch version from downloads.claude.ai`520 `Failed to fetch version from downloads.claude.ai`
516</h3>521</h3>
517 522
518설치 프로그램이 다운로드 서버에 도달할 수 없습니다. 이는 일반적으로 `downloads.claude.ai`가 네트워크에서 차단됨을 의미합니다. [네트워크 연결 확인](#check-network-connectivity)을 참조하세요.523설치 프로그램이 다운로드 서버에 도달할 수 없습니다. 이는 보통 `downloads.claude.ai`가 네트워크에서 차단되었음을 의미합니다. [네트워크 연결 확인](#check-network-connectivity)을 참조하세요.
519 524
520<h3 id="wrong-install-command-on-windows">525<h3 id="wrong-install-command-on-windows">
521 Windows에서 잘못된 설치 명령526 Windows에서 잘못된 설치 명령
522</h3>527</h3>
523 528
524`'irm' is not recognized`, `The token '&&' is not valid`, `A parameter cannot be found that matches parameter name 'fsSL'` 또는 `'bash' is not recognized as the name of a cmdlet`이 표시되면 다른 셸 또는 운영 체제의 설치 명령을 복사했습니다. 명령이 스크립트의 텍스트를 인쇄하면 부분만 실행했습니다.529`'irm' is not recognized`, `The token '&&' is not a valid statement separator`, `A parameter cannot be found that matches parameter name 'fsSL'` 또는 `'bash' is not recognized as the name of a cmdlet`이 표시되면 다른 셸 또는 운영 체제의 설치 명령을 복사했습니다. 명령이 스크립트의 텍스트를 출력하면 일부만 실행했습니다.
525 530
526* **`irm` 인식 안 됨**: CMD에 있고 PowerShell이 아닙니다. 두 가지 옵션이 있습니다:531* **`irm` not recognized**: CMD에 있으며 PowerShell이 아닙니다. 두 가지 옵션이 있습니다.
527 532
528 시작 메뉴에서 "PowerShell"을 검색하여 PowerShell을 열고 원래 설치 명령을 실행하세요:533 시작 메뉴에서 "PowerShell"을 검색하여 PowerShell을 열고 원래 설치 명령을 실행합니다.
529 534
530 ```powershell theme={null}535 ```powershell theme={null}
531 irm https://claude.ai/install.ps1 | iex536 irm https://claude.ai/install.ps1 | iex
532 ```537 ```
533 538
534 또는 CMD에 머물러 있고 CMD 설치 프로그램을 대신 사용하세요:539 또는 CMD에 머물러 있고 CMD 설치 프로그램을 대신 사용합니다.
535 540
536 ```batch theme={null}541 ```batch theme={null}
537 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd542 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
538 ```543 ```
539 544
540* **`&&` 유효하지 않음**: PowerShell에 있지만 CMD 설치 프로그램 명령을 실행했습니다. PowerShell 설치 프로그램을 사용하십시오:545* **`&&` not a valid statement separator**: PowerShell에 있지만 CMD 설치 프로그램 명령을 실행했습니다. PowerShell 설치 프로그램을 사용합니다.
541 ```powershell theme={null}546 ```powershell theme={null}
542 irm https://claude.ai/install.ps1 | iex547 irm https://claude.ai/install.ps1 | iex
543 ```548 ```
544 549
545* **`A parameter cannot be found that matches parameter name 'fsSL'`**: Windows PowerShell에서 macOS/Linux `curl -fsSL ... | bash` 설치 프로그램을 실행했습니다. 여기서 `curl`은 `Invoke-WebRequest`의 별칭이며 `-fsSL` 플래그를 거부합니다. 대신 PowerShell 설치 프로그램을 사용하세요:550* **`A parameter cannot be found that matches parameter name 'fsSL'`**: Windows PowerShell에서 macOS/Linux `curl -fsSL ... | bash` 설치 프로그램을 실행했습니다. 여기서 `curl`은 `Invoke-WebRequest`의 별칭이며 `-fsSL` 플래그를 거부합니다. PowerShell 설치 프로그램을 대신 사용합니다.
546 ```powershell theme={null}551 ```powershell theme={null}
547 irm https://claude.ai/install.ps1 | iex552 irm https://claude.ai/install.ps1 | iex
548 ```553 ```
549 554
550* **`bash` 인식 안 됨**: Windows에서 macOS/Linux 설치 프로그램을 실행했습니다. 대신 PowerShell 설치 프로그램을 사용하세요:555* **`bash` not recognized**: Windows에서 macOS/Linux 설치 프로그램을 실행했습니다. PowerShell 설치 프로그램을 대신 사용합니다.
551 ```powershell theme={null}556 ```powershell theme={null}
552 irm https://claude.ai/install.ps1 | iex557 irm https://claude.ai/install.ps1 | iex
553 ```558 ```
554 559
555* **명령이 스크립트 텍스트를 인쇄함**: 다운로드 절반을 실행하는 부분 없이 실행했습니다. `irm https://claude.ai/install.ps1`만으로는 다운로드된 스크립트를 터미널에 인쇄합니다. 이를 실행하려면 `iex`에 파이프하세요:560* **명령이 스크립트 텍스트를 출력합니다**: 실행하는 부분 없이 명령의 다운로드 절반만 실행했습니다. `irm https://claude.ai/install.ps1`은 단독으로 다운로드된 스크립트를 터미널에 출력합니다. `iex`로 파이프하여 실행합니다.
556 561
557 ```powershell theme={null}562 ```powershell theme={null}
558 irm https://claude.ai/install.ps1 | iex563 irm https://claude.ai/install.ps1 | iex
559 ```564 ```
560 565
561 CMD에서 `-o` 없이 `curl -fsSL https://claude.ai/install.cmd`는 배치 스크립트를 저장하는 대신 인쇄합니다. 완전한 명령을 실행하세요:566 CMD에서 `-o` 없이 `curl -fsSL https://claude.ai/install.cmd`는 배치 스크립트를 저장하는 대신 출력합니다. 완전한 명령을 실행합니다.
562 567
563 ```batch theme={null}568 ```batch theme={null}
564 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd569 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
565 ```570 ```
566 571
567어느 설치 프로그램을 사용하든 작동했는지 확인하세요: 새 터미널을 열고 `claude --version`을 실행하세요. 이는 `2.1.211 (Claude Code)`와 같은 버전 번호를 인쇄합니다.572어떤 설치 프로그램을 사용하든 작동했는지 확인합니다. 새 터미널을 열고 `claude --version`을 실행합니다. 이는 `2.1.211 (Claude Code)`와 같은 버전 번호를 출력합니다.
568 573
569<h3 id="running-scripts-is-disabled-on-this-system">574<h3 id="running-scripts-is-disabled-on-this-system">
570 `running scripts is disabled on this system`575 `running scripts is disabled on this system`
571</h3>576</h3>
572 577
573Windows에서 npm을 통해 Claude Code를 설치하거나 실행하면 `SecurityError`로 실패할 수 있습니다:578Windows에서 npm을 통해 Claude Code를 설치하거나 실행하면 `SecurityError`로 실패할 수 있습니다.
574 579
575```text theme={null}580```text theme={null}
576npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.581npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
578 + CategoryInfo : SecurityError: (:) [], PSSecurityException583 + CategoryInfo : SecurityError: (:) [], PSSecurityException
579```584```
580 585
581npm 설치 후 `claude`를 실행할 때 동일한 오류가 `claude.ps1`의 이름을 지정합니다. PowerShell의 실행 정책은 npm이 명령에 대해 생성하는 `.ps1` 런처 스크립트를 차단하고 있습니다. 정책은 스크립트 파일에 적용되므로 다운로드된 텍스트를 직접 실행하는 PowerShell 설치 프로그램 `irm https://claude.ai/install.ps1 | iex`에는 영향을 주지 않습니다.586npm 설치 후 `claude`를 실행할 때 동일한 오류가 `claude.ps1`의 이름을 지정합니다. PowerShell의 실행 정책이 npm이 명령에 대해 생성하는 `.ps1` 런처 스크립트를 차단합니다. 정책은 스크립트 파일에 적용되므로 다운로드된 텍스트를 직접 실행하는 PowerShell 설치 프로그램 `irm https://claude.ai/install.ps1 | iex`에는 영향을 주지 않습니다.
582 587
583**해결책:**588**해결 방법:**
584 589
5851. **사용자에 대해 로컬로 생성된 스크립트 허용**한 다음 다시 시도하세요:5901. **사용자에 대해 로컬로 생성된 스크립트 허용**한 다음 다시 시도합니다.
586 ```powershell theme={null}591 ```powershell theme={null}
587 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser592 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
588 ```593 ```
5892. **`.cmd` 런처 대신 호출**: `npm.cmd` 및 `claude.cmd`는 동일한 작업을 수행하며 정책은 이들을 다루지 않습니다.5942. **`.cmd` 런처 대신 호출**: `npm.cmd` 및 `claude.cmd`는 동일한 작업을 수행하며 정책이 이를 적용하지 않습니다.
5903. **npm 대신 [PowerShell 설치 프로그램](/docs/ko/setup#install-claude-code) 사용**. 이는 `.ps1` 스크립트가 아닌 바이너리를 설치합니다.5953. **npm 대신 [PowerShell 설치 프로그램](/docs/ko/setup#install-claude-code) 사용**. `.ps1` 스크립트가 아닌 바이너리를 설치합니다.
591 596
592<h3 id="the-process-cannot-access-the-file-during-windows-install">597<h3 id="the-process-cannot-access-the-file-during-windows-install">
593 Windows 설치 중 `The process cannot access the file`598 Windows 설치 중 `The process cannot access the file`
594</h3>599</h3>
595 600
596PowerShell 설치 프로그램이 `Failed to download binary: The process cannot access the file ... because it is being used by another process`로 실패하면 설치 프로그램이 `%USERPROFILE%\.claude\downloads`에 쓸 수 없습니다. 이는 일반적으로 이전 설치 시도가 여전히 실행 중이거나 바이러스 백신 소프트웨어가 해당 폴더의 부분적으로 다운로드된 바이너리를 스캔하고 있음을 의미합니다.601PowerShell 설치 프로그램이 `Failed to download binary: The process cannot access the file ... because it is being used by another process`로 실패하면 설치 프로그램이 `%USERPROFILE%\.claude\downloads`에 쓸 수 없습니다. 이는 보통 이전 설치 시도가 여전히 실행 중이거나 바이러스 백신 소프트웨어가 해당 폴더의 부분적으로 다운로드된 바이너리를 스캔하고 있음을 의미합니다.
597 602
598설치 프로그램을 실행하는 다른 PowerShell 창을 닫고 바이러스 백신 스캔이 파일을 해제할 때까지 기다리세요. 그런 다음 다운로드 폴더를 삭제하고 설치 프로그램을 다시 실행하세요:603설치 프로그램을 실행하는 다른 PowerShell 창을 닫고 바이러스 백신 스캔이 파일을 해제할 때까지 기다립니다. 그런 다음 다운로드 폴더를 삭제하고 설치 프로그램을 다시 실행합니다.
599 604
600```powershell theme={null}605```powershell theme={null}
601Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"606Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
606 Windows에서 업데이트 후 `claude.exe` 누락611 Windows에서 업데이트 후 `claude.exe` 누락
607</h3>612</h3>
608 613
609Claude Code가 Windows에서 업데이트된 직후 터미널이 `'claude' is not recognized`를 보고하면 `%USERPROFILE%\.local\bin`에 여전히 `claude.exe`가 포함되어 있는지 확인하세요. 해당 디렉토리가 PATH에 없으면 [PATH 수정](#command-not-found-claude-after-installation)을 참조하세요. Windows에서 업데이트하려면 Claude Code는 기존 `claude.exe`를 백업으로 옆으로 이름을 바꾸고 새 버전을 제자리에 이동합니다. 새 버전을 제자리에 이동하지 못하고 Claude Code가 백업을 다시 이름을 바꿀 수도 없으면 디렉토리는 백업을 유지하지만 `claude.exe`가 없습니다.614터미널이 Windows에서 Claude Code가 업데이트된 직후 `'claude' is not recognized`를 보고하면 `%USERPROFILE%\.local\bin`에 여전히 `claude.exe`가 포함되어 있는지 확인합니다. 해당 디렉토리가 PATH에 없으면 [PATH 수정](#command-not-found-claude-after-installation)을 참조하세요. Windows에서 업데이트하려면 Claude Code가 기존 `claude.exe`를 백업으로 이름을 바꾸고 새 버전을 제자리에 이동합니다. 새 버전을 제자리에 이동하지 못하고 Claude Code가 백업을 다시 이름을 바꿀 수도 없으면 디렉토리는 백업을 유지하지만 `claude.exe`가 없습니다.
610 615
611백업은 `claude.exe.old.` 다음에 숫자 타임스탬프가 오는 동일한 디렉토리의 파일입니다. PowerShell에서 다음을 실행하여 최신 백업을 `claude.exe`로 이름을 바꾸세요:616백업은 `claude.exe.old.` 다음에 숫자 타임스탬프가 오는 이름으로 시작하는 동일한 디렉토리의 파일입니다. PowerShell에서 다음을 실행하여 최신 백업을 `claude.exe`로 이름을 바꿉니다.
612 617
613```powershell theme={null}618```powershell theme={null}
614Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe619Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe
615```620```
616 621
617그런 다음 `claude --version`을 실행하여 수정을 확인하세요. 복원된 `claude.exe`는 버전 번호를 인쇄합니다.622그런 다음 `claude --version`을 실행하여 수정을 확인합니다. 복원된 `claude.exe`는 버전 번호를 출력합니다.
618 623
619`claude.exe.old.*` 파일이 없거나 이름 바꾸기 후에도 `claude`가 여전히 실패하면 대신 다시 설치하세요:624`claude.exe.old.*` 파일이 없거나 이름 바꾸기 후에도 `claude`가 실패하면 대신 다시 설치합니다.
620 625
621```powershell theme={null}626```powershell theme={null}
622irm https://claude.ai/install.ps1 | iex627irm https://claude.ai/install.ps1 | iex
623```628```
624 629
625v2.1.281 이전에는 Claude Code가 `claude.exe`가 여전히 누락된 동안 백업을 삭제할 수 있었습니다.630v2.1.281 이전에는 Claude Code가 `claude.exe`가 여전히 누락된 상태에서 백업을 삭제할 수 있었습니다.
626 631
627<h3 id="install-killed-on-low-memory-linux-servers">632<h3 id="install-killed-on-low-memory-linux-servers">
628 저메모리 Linux 서버에서 설치 중단633 메모리 부족 Linux 서버에서 설치 중단
629</h3>634</h3>
630 635
631설치 중에 `Killed` 메시지가 표시되면 일반적으로 Linux OOM(메모리 부족) killer가 시스템이 메모리 부족으로 인해 `claude install` 단계를 종료했음을 의미합니다. 이는 작은 VPS 및 클라우드 인스턴스에서 일반적입니다. 설치 스크립트는 원인을 보고하고 종료 코드 137로 종료됩니다. 이 예에서 줄 번호와 프로세스 ID는 릴리스 및 실행에 따라 다릅니다:636설치 중 `Killed` 메시지는 보통 Linux OOM(메모리 부족) 킬러가 시스템의 여유 메모리가 부족하여 `claude install` 단계를 종료했음을 의미합니다. 이는 작은 VPS 및 클라우드 인스턴스에서 일반적입니다. 설치 스크립트는 원인을 보고하고 코드 137로 종료합니다. 이 예에서 줄 번호와 프로세스 ID는 릴리스 및 실행에 따라 다릅니다.
632 637
633```text theme={null}638```text theme={null}
634Setting up Claude Code...639Setting up Claude Code...
637Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.642Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.
638```643```
639 644
640설치에는 대략 512MB의 여유 메모리가 필요하며 Claude Code를 실행하려면 더 많은 메모리가 필요합니다. [시스템 요구사항](/docs/ko/setup#system-requirements)을 참조하세요.645설치하려면 대략 512MB의 여유 메모리가 필요하며, Claude Code를 실행하려면 더 많은 메모리가 필요합니다. [시스템 요구 사항](/docs/ko/setup#system-requirements)을 참조하세요.
641 646
642**해결책:**647**해결 방법:**
643 648
6441. **서버의 RAM이 제한된 경우 스왑 공간 추가**. 스왑은 디스크 공간을 오버플로우 메모리로 사용하여 낮은 물리적 RAM으로도 설치를 완료할 수 있게 합니다.6491. **서버의 RAM이 제한되어 있으면 스왑 공간 추가**. 스왑은 디스크 공간을 오버플로우 메모리로 사용하여 물리적 RAM이 낮아도 설치를 완료할 수 있습니다.
645 650
646 2GB 스왑 파일을 만들고 활성화하세요:651 2GB 스왑 파일을 생성하고 활성화합니다.
647 652
648 ```bash theme={null}653 ```bash theme={null}
649 sudo fallocate -l 2G /swapfile654 sudo fallocate -l 2G /swapfile
652 sudo swapon /swapfile657 sudo swapon /swapfile
653 ```658 ```
654 659
655 그런 다음 설치를 다시 시도하세요:660 그런 다음 설치를 다시 시도합니다.
656 661
657 ```bash theme={null}662 ```bash theme={null}
658 curl -fsSL https://claude.ai/install.sh | bash663 curl -fsSL https://claude.ai/install.sh | bash
659 ```664 ```
660 665
6612. **설치하기 전에 다른 프로세스를 닫아** 메모리를 확보하세요.6662. **설치 전에 다른 프로세스를 닫아** 메모리를 확보합니다.
662 667
6633. **가능하면 더 큰 인스턴스 사용**. Claude Code는 최소 4GB의 RAM이 필요합니다.6683. **가능하면 더 큰 인스턴스 사용**. Claude Code는 최소 4GB의 RAM이 필요합니다.
664 669
666 Docker에서 설치 중단671 Docker에서 설치 중단
667</h3>672</h3>
668 673
669Docker 컨테이너에서 Claude Code를 설치할 때 root로 `/`에 설치하면 중단될 수 있습니다.674Docker 컨테이너에서 Claude Code를 설치할 때 `/`에 루트로 설치하면 중단될 수 있습니다.
670 675
671**해결책:**676**해결 방법:**
672 677
6731. **설치 프로그램을 실행하기 전에 작업 디렉토리 설정**. `/`에서 실행하면 설치 프로그램이 전체 파일 시스템을 스캔하여 과도한 메모리 사용을 유발합니다. `WORKDIR`을 설정하면 스캔이 작은 디렉토리로 제한됩니다:6781. **설치 프로그램을 실행하기 전에 작업 디렉토리 설정**. `/`에서 실행하면 설치 프로그램이 전체 파일 시스템을 스캔하여 과도한 메모리 사용을 유발합니다. `WORKDIR`을 설정하면 스캔이 작은 디렉토리로 제한됩니다.
674 ```dockerfile theme={null}679 ```dockerfile theme={null}
675 WORKDIR /tmp680 WORKDIR /tmp
676 RUN curl -fsSL https://claude.ai/install.sh | bash681 RUN curl -fsSL https://claude.ai/install.sh | bash
677 ```682 ```
678 683
6792. **Docker에 더 많은 메모리 제공** Docker Desktop을 사용하는 경우. **Settings > Resources**를 열고 메모리 제한을 높이고 빌드를 다시 실행하세요.6842. **Docker Desktop을 사용하는 경우 Docker에 더 많은 메모리 제공**. 빌드 컨테이너는 Docker Desktop 가상 머신에 할당된 메모리를 공유하므로 Docker Desktop에서 **Settings > Resources**를 열고 메모리 제한을 높인 다음 빌드를 다시 실행합니다.
680 685
681<h3 id="raw-mode-is-not-supported-during-install">686<h3 id="raw-mode-is-not-supported-during-install">
682 설치 중 `Raw mode is not supported`687 설치 중 `Raw mode is not supported`
683</h3>688</h3>
684 689
685조직의 [서버 관리 설정](/docs/ko/server-managed-settings)에 [보안 승인](/docs/ko/server-managed-settings#security-approval-dialogs)이 필요한 변경 사항이 포함되어 있으면 Claude Code 버전 2.1.246 이전에는 `claude install` 중에 승인 대화 상자를 표시하려고 시도합니다. 대화 상자는 stdin의 터미널이 필요합니다. 설치 프로그램이 `curl -fsSL https://claude.ai/install.sh | bash`처럼 파이프에서 `claude install`을 실행하면 stdin은 터미널이 아닌 파이프이므로 설치가 `Raw mode is not supported`를 포함하는 오류로 실패합니다.690조직의 [서버 관리 설정](/docs/ko/server-managed-settings)에 [보안 승인](/docs/ko/server-managed-settings#security-approval-dialogs)이 필요한 변경 사항이 포함되어 있으면 v2.1.246 이전의 Claude Code 버전은 `claude install` 중에 승인 대화 상자를 표시하려고 시도합니다. 대화 상자는 stdin의 터미널이 필요합니다. 설치 프로그램이 `curl -fsSL https://claude.ai/install.sh | bash`처럼 파이프에서 `claude install`을 실행하면 stdin은 터미널이 아닌 파이프이므로 설치가 `Raw mode is not supported`를 포함하는 오류로 실패합니다.
686 691
687Claude Code v2.1.246 이상은 `claude install` 또는 `claude update` 중에 대화 상자를 표시하지 않습니다. 명령은 마지막으로 승인한 설정으로 실행되며 Claude Code는 다음 대화형 세션에서 대화 상자를 표시합니다. 조직의 시작 구성이 [설정 가져오기를 기다리는 경우](/docs/ko/server-managed-settings#enforce-fail-closed-startup)(예: `forceRemoteSettingsRefresh`를 설정할 때) 대화 상자는 여전히 이러한 명령 중에 나타나며 파이프에서 실행되는 설치는 여전히 실패합니다.692Claude Code v2.1.246 이상은 `claude install` 또는 `claude update` 중에 대화 상자를 표시하지 않습니다. 명령은 마지막으로 승인한 설정으로 실행되며 Claude Code는 다음 대화형 세션에서 대화 상자를 표시합니다. 조직의 시작 구성이 [설정 가져오기를 기다리는](/docs/ko/server-managed-settings#enforce-fail-closed-startup) 경우(예: `forceRemoteSettingsRefresh`를 설정할 때) 대화 상자는 여전히 이러한 명령 중에 나타나며 파이프에서 실행되는 설치는 여전히 실패합니다.
688 693
689다른 모든 구성에서 설치 프로그램을 다시 실행하면 이 오류를 지나갑니다. 스크립트는 이전 버전을 설치하도록 요청할 때도 최신 릴리스의 `install` 명령을 실행하기 때문입니다. 플랫폼에 대한 명령을 다시 실행하세요:694다른 모든 구성에서는 설치 프로그램을 다시 실행하면 이 오류를 지나갑니다. 스크립트는 이전 버전을 설치하도록 요청할 때도 최신 릴리스의 `install` 명령을 실행하기 때문입니다. 플랫폼에 대한 명령을 다시 실행합니다.
690 695
691<Tabs>696<Tabs>
692 <Tab title="macOS/Linux">697 <Tab title="macOS/Linux">
702 </Tab>707 </Tab>
703</Tabs>708</Tabs>
704 709
705`claude --version`은 다시 실행이 설치한 버전을 인쇄합니다.710`claude --version`은 다시 실행이 설치한 버전을 출력합니다.
706 711
707<h3 id="claude-update-or-claude-doctor-hangs">712<h3 id="claude-update-or-claude-doctor-hangs">
708 `claude update` 또는 `claude doctor` 중단713 `claude update` 또는 `claude doctor` 중단
709</h3>714</h3>
710 715
711`claude update` 및 `claude doctor`는 셸 구성 파일에서 오래된 `claude` 별칭을 스캔합니다: `~/.zshrc`, `~/.bashrc` 및 `~/.config/fish/config.fish`. macOS에서는 존재하는 `~/.bash_profile`, `~/.bash_login` 또는 `~/.profile` 중 첫 번째입니다. `ZDOTDIR`을 설정하면 Zsh 파일은 `$ZDOTDIR/.zshrc`입니다. 이러한 경로 중 하나가 디렉토리인 경우 Claude Code는 이를 건너뛰고 두 명령 모두 정상적으로 완료됩니다. v2.1.214 이전에는 이러한 경로의 디렉토리로 인해 두 명령 모두 중단되었으며 `/status`의 System diagnostics 섹션이 비어 있었습니다. `claude doctor`는 출력 없이 중단되었습니다. `claude update`는 `Checking for updates`를 인쇄한 직후 중단되었습니다.716`claude update` 및 `claude doctor`는 셸 구성 파일에서 오래된 `claude` 별칭을 스캔합니다. `~/.zshrc`, `~/.bashrc` 및 `~/.config/fish/config.fish`, macOS에서는 존재하는 `~/.bash_profile`, `~/.bash_login` 또는 `~/.profile` 중 첫 번째입니다. `ZDOTDIR`을 설정하면 Zsh 파일은 `$ZDOTDIR/.zshrc`입니다. 이러한 경로 중 하나가 디렉토리인 경우 Claude Code는 이를 건너뛰고 두 명령 모두 정상적으로 완료됩니다. v2.1.214 이전에는 이러한 경로의 디렉토리가 두 명령을 중단하게 했으며 `/status`의 System diagnostics 섹션을 비워 두었습니다. `claude doctor`는 출력 없이 중단되었습니다. `claude update`는 `Checking for updates`를 출력한 직후 중단되었습니다.
712 717
713이전 버전에서 중단을 겪으면 디렉토리를 찾으세요. 이 명령의 출력에서 `d`로 시작하는 줄은 해당 경로를 디렉토리로 표시합니다. `No such file or directory` 줄은 해당 경로에 아무것도 없으며 원인이 아님을 의미합니다:718이전 버전에서 중단이 발생하면 디렉토리를 찾습니다. 이 명령의 출력에서 `d`로 시작하는 줄은 해당 경로를 디렉토리로 표시합니다. `No such file or directory` 줄은 해당 경로에 아무것도 없으며 원인이 아님을 의미합니다.
714 719
715```bash theme={null}720```bash theme={null}
716ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish721ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish
717```722```
718 723
719디렉토리를 옆으로 이동하거나 v2.1.214 이상으로 업데이트하세요. `claude update`는 영향을 받는 버전에서 중단되므로 [설치 스크립트](/docs/ko/setup#install-claude-code)를 다시 실행하여 업데이트하세요.724디렉토리를 옆으로 이동하거나 v2.1.214 이상으로 업데이트합니다. `claude update`는 영향을 받는 버전에서 중단되므로 [설치 스크립트](/docs/ko/setup#install-claude-code)를 다시 실행하여 업데이트합니다.
720 725
721<h3 id="claude-desktop-overrides-the-claude-command-on-windows">726<h3 id="claude-desktop-overrides-the-claude-command-on-windows">
722 Claude Desktop이 Windows에서 `claude` 명령 무시727 Claude Desktop이 Windows에서 `claude` 명령을 재정의합니다
723</h3>728</h3>
724 729
725Claude Desktop의 이전 버전을 설치한 경우 `WindowsApps` 디렉토리에 `Claude.exe`를 등록할 수 있으며, 이는 Claude Code CLI보다 PATH 우선순위를 가집니다. `claude`를 실행하면 CLI 대신 Desktop 앱이 열립니다.730이전 버전의 Claude Desktop을 설치했으면 `WindowsApps` 디렉토리에 `Claude.exe`를 등록할 수 있으며, 이는 Claude Code CLI보다 PATH 우선 순위를 가집니다. `claude`를 실행하면 CLI 대신 Desktop 앱이 열립니다.
726 731
727Claude Desktop을 최신 버전으로 업데이트하여 이 문제를 해결하세요.732Claude Desktop을 최신 버전으로 업데이트하여 이 문제를 해결합니다.
728 733
729<h3 id="claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell">734<h3 id="claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell">
730 Windows에서 Claude Code는 Git for Windows(Bash용) 또는 PowerShell 필요735 Claude Code on Windows requires either Git for Windows (for bash) or PowerShell
731</h3>736</h3>
732 737
733Git for Windows는 선택 사항입니다. Claude Code는 Git Bash가 없을 때 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)를 사용하므로 이 오류는 어느 셸도 찾을 수 없음을 의미합니다.738Git for Windows는 선택 사항입니다. Claude Code는 Git Bash가 없을 때 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)를 사용하므로 이 오류는 어느 셸도 찾을 수 없음을 의미합니다.
734 739
735**PowerShell이 PATH에서 누락된 경우** 기본 위치는 `C:\Windows\System32\WindowsPowerShell\v1.0\`입니다. 해당 디렉토리를 `PATH`에 추가하거나 `pwsh`를 제공하는 [PowerShell 7](https://aka.ms/powershell)을 설치하세요.740**PowerShell이 PATH에서 누락된 경우** 기본 위치는 `C:\Windows\System32\WindowsPowerShell\v1.0\`입니다. 해당 디렉토리를 `PATH`에 추가하거나 `pwsh`를 제공하는 [PowerShell 7](https://aka.ms/powershell)을 설치합니다.
736 741
737**Git for Windows를 설치하려면** [git-scm.com/downloads/win](https://git-scm.com/downloads/win)에서 다운로드하세요. 설정 중에 "Add to PATH"를 선택하세요. 설치 후 터미널을 다시 시작하세요. 설치하면 Bash 도구가 활성화되어 Bash 기반 스크립트 및 도구로 작업할 때 유용합니다.742**Git for Windows를 대신 설치하려면** [git-scm.com/downloads/win](https://git-scm.com/downloads/win)에서 다운로드합니다. 설정 중에 "Add to PATH"를 선택합니다. 설치 후 터미널을 다시 시작합니다. 설치하면 Bash 도구가 활성화되어 Bash 기반 스크립트 및 도구로 작업할 때 유용합니다.
738 743
739**Git이 이미 설치되어 있지만** Claude Code가 찾을 수 없으면 위치를 Claude Code가 확인하는 위치와 비교하세요. `CLAUDE_CODE_GIT_BASH_PATH`가 설정되지 않으면 Claude Code는 다음 순서로 `bash.exe`를 찾습니다:744**Git이 이미 설치되어 있지만 Claude Code가 찾을 수 없으면** 해당 위치를 Claude Code가 확인하는 위치와 비교합니다. `CLAUDE_CODE_GIT_BASH_PATH`가 설정되지 않으면 Claude Code는 다음 순서로 `bash.exe`를 찾습니다.
740 745
7411. 기본 설치 위치 `C:\Program Files\Git` 및 `C:\Program Files (x86)\Git`.7461. 기본 설치 위치 `C:\Program Files\Git` 및 `C:\Program Files (x86)\Git`.
7422. `PATH`의 `git`. 해당 Git 설치에서 `bin\bash.exe`를 사용합니다.7472. `PATH`의 `git`을 사용하여 해당 Git 설치의 `bin\bash.exe`.
743 748
7442단계에서 Claude Code는 Claude Code를 시작한 폴더에 있거나 `node_modules` 또는 `.venv` 또는 `env`와 같은 가상 환경 폴더를 포함하는 경로 아래에 있는 `git`을 건너뜁니다. 예를 들어 `C:\dev\env\myproject`에서 시작했을 때 `C:\dev\env\myproject\Git`. 이는 Claude Code가 프로젝트가 거기에 배치한 실행 파일을 실행하지 않도록 합니다. Git이 그런 위치에 있으면 `CLAUDE_CODE_GIT_BASH_PATH`를 가리키세요.7492단계에서 Claude Code는 Claude Code를 시작한 폴더에 있거나 `node_modules` 또는 `.venv` 또는 `env`와 같은 가상 환경 폴더를 포함하는 경로 아래에 있는 `git`을 건너뜁니다. 예를 들어 `C:\dev\env\myproject`에서 시작했을 때 `C:\dev\env\myproject\Git`. 이는 Claude Code가 프로젝트가 배치한 실행 파일을 실행하지 않도록 합니다. Git이 그러한 위치에 있으면 `CLAUDE_CODE_GIT_BASH_PATH`를 가리킵니다.
745 750
746**Claude Code를 특정 Git 설치로 가리키려면** PowerShell에서 `where.exe git`을 실행하여 찾고 해당 설치에서 `bin\bash.exe` 경로를 [settings.json 파일](/docs/ko/settings)에서 `CLAUDE_CODE_GIT_BASH_PATH`로 설정하세요:751**Claude Code를 특정 Git 설치로 가리키려면** PowerShell에서 `where.exe git`을 실행하여 찾은 다음 해당 설치의 `bin\bash.exe` 경로를 [settings.json 파일](/docs/ko/settings)에서 `CLAUDE_CODE_GIT_BASH_PATH`로 설정합니다.
747 752
748```json theme={null}753```json theme={null}
749{754{
753}758}
754```759```
755 760
756**`CLAUDE_CODE_GIT_BASH_PATH`가 올바른 경로로 설정되고 파일이 존재하지만** Claude Code가 여전히 사용하지 않으면 파일의 이름을 먼저 확인하세요. Claude Code는 `bash.exe`, `sh.exe`, `bash` 또는 `sh`라는 파일만 허용합니다. Git for Windows의 `git-bash.exe` 런처와 같은 다른 이름이면 변수를 무시하고 설정되지 않은 것처럼 자동 감지하며 `--debug`로 볼 수 있는 경고를 기록합니다. 존재하지 않는 경로는 동일한 폴백과 경고를 받습니다. v2.1.219 이전에는 Claude Code가 이름을 확인하지 않고 모든 기존 파일을 셸로 사용했으며 경로가 존재하지 않으면 `Claude Code was unable to find CLAUDE_CODE_GIT_BASH_PATH path`로 시작 시 종료되었습니다.761**`CLAUDE_CODE_GIT_BASH_PATH`가 올바른 경로로 설정되고 파일이 존재하지만** Claude Code가 여전히 사용하지 않으면 먼저 파일의 이름을 확인합니다. Claude Code는 `bash.exe`, `sh.exe`, `bash` 또는 `sh`라는 이름의 파일만 허용합니다. Git for Windows의 `git-bash.exe` 런처와 같은 다른 이름의 경우 변수를 무시하고 설정되지 않은 것처럼 자동 감지하며 `--debug`로 볼 수 있는 경고를 기록합니다. 존재하지 않는 경로는 동일한 폴백 및 경고를 받습니다. v2.1.219 이전에는 Claude Code가 이름을 확인하지 않고 존재하는 모든 파일을 셸로 사용했으며 경로가 존재하지 않을 때 `Claude Code was unable to find CLAUDE_CODE_GIT_BASH_PATH path`로 시작 시 종료되었습니다.
757 762
758파일의 이름이 맞으면 AppLocker, 그룹 정책 소프트웨어 제한 정책 또는 EDR 에이전트와 같은 엔드포인트 보안 소프트웨어가 간섭할 수 있습니다. IT 팀에 `claude.exe` 및 `cmd.exe` 및 `bash.exe`를 포함한 생성하는 프로세스를 엔드포인트 보호 정책에서 허용 목록에 추가하도록 요청하세요.763파일의 이름이 맞으면 AppLocker, 그룹 정책 소프트웨어 제한 정책 또는 EDR 에이전트와 같은 엔드포인트 보안 소프트웨어가 간섭할 수 있습니다. IT 팀에 엔드포인트 보호 정책에서 `claude.exe` 및 `cmd.exe` 및 `bash.exe`를 포함한 생성하는 프로세스를 허용 목록에 추가하도록 요청합니다.
759 764
760<h3 id="claude-code-does-not-support-32-bit-windows">765<h3 id="claude-code-does-not-support-32-bit-windows">
761 Claude Code는 32비트 Windows를 지원하지 않음766 Claude Code는 32비트 Windows를 지원하지 않습니다
762</h3>767</h3>
763 768
764Windows는 시작 메뉴에 두 개의 PowerShell 항목을 포함합니다: `Windows PowerShell` 및 `Windows PowerShell (x86)`. x86 항목은 32비트 프로세스로 실행되며 64비트 머신에서도 이 오류를 트리거합니다. 어느 경우인지 확인하려면 오류를 생성한 동일한 창에서 이를 실행하세요:769Windows는 시작 메뉴에 두 개의 PowerShell 항목을 포함합니다. `Windows PowerShell` 및 `Windows PowerShell (x86)`. x86 항목은 32비트 프로세스로 실행되며 64비트 머신에서도 이 오류를 트리거합니다. 어느 경우인지 확인하려면 오류를 생성한 동일한 창에서 다음을 실행합니다.
765 770
766```powershell theme={null}771```powershell theme={null}
767[Environment]::Is64BitOperatingSystem772[Environment]::Is64BitOperatingSystem
768```773```
769 774
770이것이 `True`를 인쇄하면 운영 체제는 정상입니다. 창을 닫고 x86 접미사 없이 `Windows PowerShell`을 열고 설치 명령을 다시 실행하세요.775이것이 `True`를 출력하면 운영 체제는 정상입니다. 창을 닫고 x86 접미사 없이 `Windows PowerShell`을 열고 설치 명령을 다시 실행합니다.
771 776
772이것이 `False`를 인쇄하면 32비트 Windows 버전을 사용 중입니다. Claude Code는 64비트 운영 체제가 필요합니다. [시스템 요구사항](/docs/ko/setup#system-requirements)을 참조하세요.777이것이 `False`를 출력하면 32비트 Windows 버전에 있습니다. Claude Code는 64비트 운영 체제가 필요합니다. [시스템 요구 사항](/docs/ko/setup#system-requirements)을 참조하세요.
773 778
774<h3 id="linux-musl-or-glibc-binary-mismatch">779<h3 id="linux-musl-or-glibc-binary-mismatch">
775 Linux musl 또는 glibc 바이너리 불일치780 Linux musl 또는 glibc 바이너리 불일치
776</h3>781</h3>
777 782
778설치 후 `libstdc++.so.6` 또는 `libgcc_s.so.1`과 같은 누락된 공유 라이브러리에 대한 오류가 표시되면 설치 프로그램이 시스템에 맞는 잘못된 바이너리 변형을 다운로드했을 수 있습니다.783설치 후 `libstdc++.so.6` 또는 `libgcc_s.so.1`과 같은 누락된 공유 라이브러리에 대한 오류가 표시되면 설치 프로그램이 시스템에 대해 잘못된 바이너리 변형을 다운로드했을 수 있습니다.
779 784
780```text theme={null}785```text theme={null}
781Error loading shared library libstdc++.so.6: No such file or directory786Error loading shared library libstdc++.so.6: No such file or directory
782```787```
783 788
784이는 musl 크로스 컴파일 패키지가 설치된 glibc 기반 시스템에서 발생할 수 있으며, 설치 프로그램이 시스템을 musl로 잘못 감지하게 합니다.789이는 musl 교차 컴파일 패키지가 설치된 glibc 기반 시스템에서 발생할 수 있으며, 설치 프로그램이 시스템을 musl로 잘못 감지하게 합니다.
785 790
786**해결책:**791**해결 방법:**
787 792
7881. **시스템이 어느 libc를 사용하는지 확인**:7931. **시스템이 사용하는 libc 확인**:
789 ```bash theme={null}794 ```bash theme={null}
790 ldd --version 2>&1 | head -1795 ldd --version 2>&1 | head -1
791 ```796 ```
792 `GNU libc` 또는 `GLIBC`를 언급하는 출력은 glibc를 의미합니다. `musl`을 언급하는 출력은 musl을 의미합니다.797 `GNU libc` 또는 `GLIBC`를 언급하는 출력은 glibc를 의미합니다. `musl`을 언급하는 출력은 musl을 의미합니다.
793 798
7942. **glibc에 있지만 musl 바이너리를 받은 경우** 설치를 제거하고 다시 설치하세요. `https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json`의 매니페스트를 사용하여 올바른 바이너리를 수동으로 다운로드할 수도 있습니다. `ldd --version` 및 `ls /lib/libc.musl*`의 출력과 함께 [GitHub 이슈](https://github.com/anthropics/claude-code/issues)를 제출하세요.7992. **glibc에 있지만 musl 바이너리를 받은 경우** 설치를 제거하고 다시 설치합니다. `https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json`의 매니페스트를 사용하여 올바른 바이너리를 수동으로 다운로드할 수도 있습니다. `ldd --version` 및 `ls /lib/libc.musl*`의 출력으로 [GitHub 이슈](https://github.com/anthropics/claude-code/issues)를 제출합니다.
795 800
7963. **실제로 musl에 있는 경우** Alpine Linux와 같이 필요한 패키지를 설치하세요:8013. **실제로 Alpine Linux와 같은 musl에 있으면** 필요한 패키지를 설치합니다.
797 ```bash theme={null}802 ```bash theme={null}
798 apk add libgcc libstdc++ ripgrep803 apk add libgcc libstdc++ ripgrep
799 ```804 ```
803 `Illegal instruction`808 `Illegal instruction`
804</h3>809</h3>
805 810
806`claude`를 실행하거나 설치 프로그램이 `Illegal instruction`을 인쇄하면 네이티브 바이너리는 프로세서가 지원하지 않는 CPU 명령어를 사용합니다. 두 가지 서로 다른 원인이 있습니다.811`claude`를 실행하거나 설치 프로그램이 `Illegal instruction`을 출력하면 네이티브 바이너리가 프로세서가 지원하지 않는 CPU 명령을 사용합니다. 두 가지 서로 다른 원인이 있습니다.
807 812
808**아키텍처 불일치.** 설치 프로그램이 잘못된 바이너리를 다운로드했습니다. 예를 들어 ARM 서버의 x86. macOS 또는 Linux에서 `uname -m`으로 확인하거나 PowerShell에서 `$env:PROCESSOR_ARCHITECTURE`로 확인하세요. 결과가 받은 바이너리와 일치하지 않으면 출력과 함께 [GitHub 이슈](https://github.com/anthropics/claude-code/issues)를 제출하세요.813**아키텍처 불일치.** 설치 프로그램이 잘못된 바이너리를 다운로드했습니다. 예를 들어 ARM 서버의 x86. macOS 또는 Linux에서 `uname -m`으로 확인하거나 PowerShell에서 `$env:PROCESSOR_ARCHITECTURE`로 확인합니다. 결과가 받은 바이너리와 일치하지 않으면 출력으로 [GitHub 이슈](https://github.com/anthropics/claude-code/issues)를 제출합니다.
809 814
810**누락된 AVX 명령어 세트.** 아키텍처는 올바르지만 여전히 `Illegal instruction`이 표시되면 CPU에 바이너리가 필요로 하는 AVX 또는 다른 명령어가 없을 가능성이 높습니다. 이는 대략 2013년 이전의 Intel 및 AMD 프로세서에 영향을 미치며, 하이퍼바이저가 게스트에게 AVX를 전달하지 않는 가상 머신에도 영향을 미칩니다.815**AVX 명령 집합 누락.** 아키텍처는 맞지만 여전히 `Illegal instruction`이 표시되면 CPU에 바이너리가 필요로 하는 AVX 또는 다른 명령이 없을 가능성이 높습니다. 이는 대략 2013년 이전의 Intel 및 AMD 프로세서와 하이퍼바이저가 게스트에 AVX를 전달하지 않는 가상 머신에 영향을 줍니다.
811 816
812VPS 또는 VM에서 `grep -m1 -ow avx /proc/cpuinfo`를 실행하세요. 빈 결과는 AVX를 게스트에서 사용할 수 없음을 의미합니다.817VPS 또는 VM에서 `grep -m1 -ow avx /proc/cpuinfo`를 실행합니다. 빈 결과는 AVX를 게스트에서 사용할 수 없음을 의미합니다.
813 818
814네이티브 바이너리 해결 방법이 없습니다. [이슈 #50384](https://github.com/anthropics/claude-code/issues/50384)를 추적하고 Linux에서 `grep -m1 "model name" /proc/cpuinfo`의 CPU 모델 또는 macOS에서 `sysctl -n machdep.cpu.brand_string`을 보고할 때 포함하세요.819네이티브 바이너리 해결 방법이 없습니다. [이슈 #50384](https://github.com/anthropics/claude-code/issues/50384)에서 상태를 추적하고 보고할 때 Linux의 `grep -m1 "model name" /proc/cpuinfo` 또는 macOS의 `sysctl -n machdep.cpu.brand_string`에서 CPU 모델을 포함합니다.
815 820
816대체 설치 방법은 동일한 네이티브 바이너리를 다운로드하며 어느 원인도 해결하지 않습니다.821대체 설치 방법은 동일한 네이티브 바이너리를 다운로드하며 어느 원인도 해결하지 않습니다.
817 822
819 macOS에서 `dyld: cannot load`824 macOS에서 `dyld: cannot load`
820</h3>825</h3>
821 826
822설치 중에 `dyld: Symbol not found`, `dyld: cannot load` 또는 `Abort trap: 6`이 표시되면 바이너리는 macOS 버전 또는 하드웨어와 호환되지 않습니다.827설치 중에 `dyld: Symbol not found`, `dyld: cannot load` 또는 `Abort trap: 6`이 표시되면 바이너리가 macOS 버전 또는 하드웨어와 호환되지 않습니다.
823 828
824`libicucore`를 참조하는 `Symbol not found` 오류는 macOS 버전이 바이너리가 지원하는 것보다 오래되었음을 의미합니다:829`libicucore`를 참조하는 `Symbol not found` 오류는 macOS 버전이 바이너리가 지원하는 것보다 오래되었음을 의미합니다.
825 830
826```text theme={null}831```text theme={null}
827dyld: Symbol not found: _ubrk_clone832dyld: Symbol not found: _ubrk_clone
829 Expected in: /usr/lib/libicucore.A.dylib834 Expected in: /usr/lib/libicucore.A.dylib
830```835```
831 836
832로더는 대신 바이너리의 로드 명령을 거부할 수 있으며, 이는 macOS 버전이 너무 오래되었음을 의미합니다:837로더는 대신 바이너리의 로드 명령을 거부할 수 있으며, 이는 macOS 버전이 너무 오래되었음을 의미합니다.
833 838
834```text theme={null}839```text theme={null}
835dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)840dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
836Abort trap: 6841Abort trap: 6
837```842```
838 843
839**해결책:**844**해결 방법:**
840 845
8411. **macOS 버전 확인**: Claude Code는 macOS 13.0 이상이 필요합니다. Apple 메뉴를 열고 이 Mac에 관하여를 선택하여 버전을 확인하세요.8461. **macOS 버전 확인**: Claude Code는 macOS 13.0 이상이 필요합니다. Apple 메뉴를 열고 이 Mac에 대해를 선택하여 버전을 확인합니다.
842 847
8432. **이전 버전을 사용 중인 경우 macOS 업데이트**. 바이너리는 이전 macOS 버전이 지원하지 않는 로드 명령 및 시스템 라이브러리를 사용합니다. Homebrew와 같은 대체 설치 방법은 동일한 바이너리를 다운로드하며 이 오류를 해결하지 않습니다.8482. **이전 버전에 있으면 macOS 업데이트**. 바이너리는 이전 macOS 버전이 지원하지 않는 로드 명령 및 시스템 라이브러리를 사용합니다. Homebrew와 같은 대체 설치 방법은 동일한 바이너리를 다운로드하며 이 오류를 해결하지 않습니다.
844 849
845<h3 id="exec-format-error-on-wsl1">850<h3 id="exec-format-error-on-wsl1">
846 WSL1에서 `Exec format error`851 WSL1에서 `Exec format error`
847</h3>852</h3>
848 853
849WSL에서 `claude`를 실행하면 `cannot execute binary file: Exec format error`가 인쇄되면 WSL1에 있으며 [이슈 #38788](https://github.com/anthropics/claude-code/issues/38788)에서 추적되는 알려진 네이티브 바이너리 회귀를 겪고 있습니다. 바이너리의 프로그램 헤더가 WSL1의 로더가 처리할 수 없는 방식으로 변경되었습니다.854WSL에서 `claude`를 실행하면 `cannot execute binary file: Exec format error`가 출력되면 WSL1에 있으며 [이슈 #38788](https://github.com/anthropics/claude-code/issues/38788)에서 추적되는 알려진 네이티브 바이너리 회귀에 직면하고 있습니다. 바이너리의 프로그램 헤더가 WSL1의 로더가 처리할 수 없는 방식으로 변경되었습니다.
850 855
851가장 깔끔한 수정은 PowerShell에서 배포판을 WSL2로 변환하는 것입니다:856가장 깔끔한 수정은 PowerShell에서 배포판을 WSL2로 변환하는 것입니다.
852 857
853```powershell theme={null}858```powershell theme={null}
854wsl --set-version <DistroName> 2859wsl --set-version <DistroName> 2
855```860```
856 861
857WSL1에 머물러야 하는 경우 동적 링커를 통해 바이너리를 호출하세요. WSL 내 `~/.bashrc`에 이 함수를 추가하고 홈 디렉토리가 다르면 경로를 바꾸세요:862WSL1에 머물러야 하면 동적 링커를 통해 바이너리를 호출합니다. WSL 내의 `~/.bashrc`에 이 함수를 추가하고 홈 디렉토리가 다르면 경로를 바꿉니다.
858 863
859```bash theme={null}864```bash theme={null}
860claude() {865claude() {
862}867}
863```868```
864 869
865그런 다음 `source ~/.bashrc`를 실행하고 `claude`를 다시 시도하세요.870그런 다음 `source ~/.bashrc`를 실행하고 `claude`를 다시 시도합니다.
866 871
867<h3 id="npm-install-errors-in-wsl">872<h3 id="npm-install-errors-in-wsl">
868 WSL에서 npm 설치 오류873 WSL에서 npm 설치 오류
869</h3>874</h3>
870 875
871이 문제는 WSL 내에서 `npm install -g`로 Claude Code를 설치한 경우 적용됩니다. [네이티브 설치 프로그램](/docs/ko/setup)을 사용한 경우 이 섹션을 건너뛰세요.876이러한 문제는 WSL 내에서 `npm install -g`로 Claude Code를 설치한 경우 적용됩니다. [네이티브 설치 프로그램](/docs/ko/setup)을 사용한 경우 이 섹션을 건너뜁니다.
872 877
873**OS 또는 플랫폼 감지 문제.** npm이 설치 중에 플랫폼 불일치를 보고하면 WSL이 Windows `npm`을 선택하고 있을 가능성이 높습니다. 먼저 `npm config set os linux`를 실행한 다음 `npm install -g @anthropic-ai/claude-code --force`로 설치하세요. `sudo`를 사용하지 마세요.878**OS 또는 플랫폼 감지 문제.** npm이 설치 중에 플랫폼 불일치를 보고하면 WSL이 Windows `npm`을 선택하고 있을 가능성이 높습니다. 먼저 `npm config set os linux`를 실행한 다음 `npm install -g @anthropic-ai/claude-code --force`로 설치합니다. `sudo`를 사용하지 마세요.
874 879
875**`claude` 실행 시 `exec: node: not found`.** WSL 환경이 Node.js의 Windows 설치를 사용하고 있을 가능성이 높습니다. `which npm` 및 `which node`로 확인하세요: `/mnt/c/`로 시작하는 경로는 Windows 바이너리이고 Linux 경로는 `/usr/`로 시작합니다. 이를 수정하려면 Linux 배포판의 패키지 관리자 또는 [`nvm`](https://github.com/nvm-sh/nvm)을 통해 Node를 설치하세요.880**`claude` 실행 시 `exec: node: not found`.** WSL 환경이 Node.js의 Windows 설치를 사용하고 있을 가능성이 높습니다. `which npm` 및 `which node`로 확인합니다. `/mnt/c/`로 시작하는 경로는 Windows 바이너리이고 Linux 경로는 `/usr/`로 시작합니다. 이를 수정하려면 Linux 배포판의 패키지 관리자 또는 [`nvm`](https://github.com/nvm-sh/nvm)을 통해 Node를 설치합니다.
876 881
877**nvm 버전 충돌.** WSL과 Windows 모두에 nvm이 설치되어 있으면 WSL에서 Node 버전을 전환하면 WSL이 기본적으로 Windows PATH를 가져오고 Windows nvm이 우선순위를 가지기 때문에 중단될 수 있습니다. 가장 일반적인 원인은 nvm이 셸에 로드되지 않는 것입니다. nvm 로더를 `~/.bashrc` 또는 `~/.zshrc`에 추가하세요:882**nvm 버전 충돌.** WSL과 Windows 모두에 nvm이 설치되어 있으면 WSL에서 Node 버전을 전환하면 WSL이 기본적으로 Windows PATH를 가져오고 Windows nvm이 우선 순위를 가지기 때문에 중단될 수 있습니다. 가장 일반적인 원인은 nvm이 셸에 로드되지 않는 것입니다. nvm 로더를 `~/.bashrc` 또는 `~/.zshrc`에 추가합니다.
878 883
879```bash theme={null}884```bash theme={null}
880export NVM_DIR="$HOME/.nvm"885export NVM_DIR="$HOME/.nvm"
882[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"887[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
883```888```
884 889
885또는 현재 세션에서 로드하세요:890또는 현재 세션에서 로드합니다.
886 891
887```bash theme={null}892```bash theme={null}
888source ~/.nvm/nvm.sh893source ~/.nvm/nvm.sh
889```894```
890 895
891nvm이 로드되었지만 Windows 경로가 여전히 우선순위를 가지면 Linux Node 경로를 명시적으로 앞에 추가하세요:896nvm이 로드되었지만 Windows 경로가 여전히 우선 순위를 가지면 Linux Node 경로를 명시적으로 앞에 추가합니다.
892 897
893```bash theme={null}898```bash theme={null}
894export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"899export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"
895```900```
896 901
897<Warning>902<Warning>
898 `appendWindowsPath = false`를 통해 Windows PATH 가져오기를 비활성화하지 마세요. WSL에서 Windows 실행 파일을 호출하는 기능이 중단됩니다. 마찬가지로 Windows 개발에 사용하는 경우 Windows에서 Node.js를 제거하지 마세요.903 `appendWindowsPath = false`를 통해 Windows PATH 가져오기를 비활성화하지 마세요. 이는 WSL에서 Windows 실행 파일을 호출하는 기능을 중단합니다. 마찬가지로 Windows 개발에 사용하는 경우 Windows에서 Node.js를 제거하지 마세요.
899</Warning>904</Warning>
900 905
901<h3 id="permission-errors-during-installation">906<h3 id="permission-errors-during-installation">
904 909
905네이티브 설치 프로그램이 권한 오류로 실패하면 대상 디렉토리를 쓸 수 없을 수 있습니다. [디렉토리 권한 확인](#check-directory-permissions)을 참조하세요.910네이티브 설치 프로그램이 권한 오류로 실패하면 대상 디렉토리를 쓸 수 없을 수 있습니다. [디렉토리 권한 확인](#check-directory-permissions)을 참조하세요.
906 911
907이전에 npm으로 설치했고 npm 특정 권한 오류를 겪고 있으면 네이티브 설치 프로그램으로 전환하세요:912이전에 npm으로 설치했고 npm 특정 권한 오류에 직면하면 네이티브 설치 프로그램으로 전환합니다.
908 913
909```bash theme={null}914```bash theme={null}
910curl -fsSL https://claude.ai/install.sh | bash915curl -fsSL https://claude.ai/install.sh | bash
911```916```
912 917
913<h3 id="native-binary-not-found-after-npm-install">918<h3 id="native-binary-not-found-after-npm-install">
914 npm 설치 후 네이티브 바이너리를 찾을 수 없음919 npm 설치 후 네이티브 바이너리를 찾을 수 없습니다
915</h3>920</h3>
916 921
917`@anthropic-ai/claude-code` npm 패키지는 `@anthropic-ai/claude-code-darwin-arm64`와 같은 플랫폼별 선택적 종속성을 통해 네이티브 바이너리를 다운로드합니다. npm은 패키지의 postinstall 스크립트를 실행하여 해당 바이너리를 `claude` 명령으로 제자리에 복사합니다. 실행될 때까지 `claude`는 자리 표시자 스크립트입니다. 다운로드 또는 postinstall 단계가 건너뛰어지면 자리 표시자가 제자리에 남아 있으며 macOS 및 Linux에서 `claude`를 실행하면 다음이 인쇄됩니다:922`@anthropic-ai/claude-code` npm 패키지는 `@anthropic-ai/claude-code-darwin-arm64`와 같은 플랫폼별 선택적 종속성으로 네이티브 바이너리를 다운로드합니다. npm은 패키지의 postinstall 스크립트를 실행하여 해당 바이너리를 `claude` 명령으로 제자리에 복사합니다. 실행될 때까지 `claude`는 자리 표시자 스크립트입니다. 다운로드 또는 postinstall 단계 중 하나가 건너뛰어지면 자리 표시자가 제자리에 남아 있으며 macOS 및 Linux에서 `claude`를 실행하면 다음이 출력됩니다.
918 923
919```text theme={null}924```text theme={null}
920Error: claude native binary not installed.925Error: claude native binary not installed.
929Or reinstall without --ignore-scripts / --omit=optional.934Or reinstall without --ignore-scripts / --omit=optional.
930```935```
931 936
932Windows에서 `bin/claude.exe`는 동일한 셸 스크립트 자리 표시자이므로 PowerShell 및 CMD는 이 메시지를 인쇄하는 대신 파일을 실행할 수 없다고 보고합니다.937Windows에서 `bin/claude.exe`는 실제 실행 파일이 아닌 동일한 셸 스크립트 자리 표시자이므로 PowerShell 및 CMD는 이 메시지를 출력하는 대신 파일을 실행할 수 없다고 보고합니다.
933 938
934다음 원인을 확인하세요:939다음 원인을 확인합니다.
935 940
936* **선택적 종속성이 비활성화됨.** npm 설치 명령에서 `--omit=optional`을 제거하고 pnpm에서 `--no-optional`을 제거하고 yarn에서 `--ignore-optional`을 제거하고 `.npmrc`가 `optional=false`를 설정하지 않는지 확인하세요. 그런 다음 다시 설치하세요. 네이티브 바이너리는 선택적 종속성으로만 제공되므로 건너뛰면 JavaScript 폴백이 없으며 `install.cjs`를 다시 실행해도 다운로드되지 않은 바이너리를 배치할 수 없습니다.941* **선택적 종속성이 비활성화됨.** npm 설치 명령에서 `--omit=optional`을 제거하고 pnpm에서 `--no-optional`을 제거하고 yarn에서 `--ignore-optional`을 제거하고 `.npmrc`가 `optional=false`를 설정하지 않는지 확인합니다. 그런 다음 다시 설치합니다. 네이티브 바이너리는 선택적 종속성으로만 제공되므로 건너뛰어지면 JavaScript 폴백이 없으며 `install.cjs`를 다시 실행해도 다운로드되지 않은 바이너리를 배치할 수 없습니다.
937* **설치 스크립트가 비활성화됨.** `--ignore-scripts` 및 일부 pnpm 구성은 postinstall 단계를 건너뛰지만 여전히 플랫폼 패키지를 다운로드합니다. 메시지가 제안하는 대로 `node node_modules/@anthropic-ai/claude-code/install.cjs`를 실행하거나 플래그 없이 다시 설치하세요. postinstall이 환경에서 실행될 수 없으면 `node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs`가 다운로드된 패키지를 찾아 시작하며, 각 시작 시 추가 Node 프로세스의 비용이 발생합니다. 래퍼가 `Could not find native binary package` 대신 인쇄하면 플랫폼 패키지가 다운로드되지 않았으므로 먼저 위의 선택적 종속성 원인을 수정하세요.942* **설치 스크립트가 비활성화됨.** `--ignore-scripts` 및 일부 pnpm 구성은 postinstall 단계를 건너뛰지만 여전히 플랫폼 패키지를 다운로드합니다. 메시지가 제안하는 대로 `node node_modules/@anthropic-ai/claude-code/install.cjs`를 실행하거나 플래그 없이 다시 설치합니다. postinstall이 환경에서 실행될 수 없으면 `node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs`가 다운로드된 패키지를 찾고 시작하며, 각 시작 시 추가 Node 프로세스의 비용이 발생합니다. 래퍼가 `Could not find native binary package`를 출력하면 플랫폼 패키지가 다운로드되지 않았으므로 먼저 위의 선택적 종속성 원인을 수정합니다.
938* **지원되지 않는 플랫폼.** 미리 빌드된 바이너리는 `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64` 및 `win32-arm64`에 대해 게시됩니다. Claude Code는 다른 플랫폼에 대한 바이너리를 제공하지 않습니다. [시스템 요구사항](/docs/ko/setup#system-requirements)을 참조하세요. FreeBSD에서 설치 프로그램은 플랫폼을 지원되지 않음으로 보고합니다. v2.1.205 이전에는 FreeBSD를 Linux로 취급하고 실행할 수 없는 바이너리를 다운로드했습니다.943* **지원되지 않는 플랫폼.** 미리 빌드된 바이너리는 `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64` 및 `win32-arm64`에 대해 게시됩니다. Claude Code는 다른 플랫폼에 대한 바이너리를 제공하지 않습니다. [시스템 요구 사항](/docs/ko/setup#system-requirements)을 참조하세요. FreeBSD에서 설치 프로그램은 플랫폼을 지원되지 않는 것으로 보고합니다. v2.1.205 이전에는 FreeBSD를 Linux로 취급하고 실행할 수 없는 바이너리를 다운로드했습니다.
939* **회사 npm 미러가 플랫폼 패키지를 누락함.** 레지스트리가 메타 패키지 외에도 8개의 `@anthropic-ai/claude-code-*` 플랫폼 패키지를 모두 미러링하는지 확인하세요.944* **회사 npm 미러가 플랫폼 패키지를 누락함.** 레지스트리가 메타 패키지 외에도 8개의 `@anthropic-ai/claude-code-*` 플랫폼 패키지를 모두 미러링하는지 확인합니다.
940 945
941<h3 id="npm-enotempty-during-update-or-reinstall">946<h3 id="npm-enotempty-during-update-or-reinstall">
942 npm `ENOTEMPTY` 오류 업데이트 또는 재설치 중947 npm 업데이트 또는 재설치 중 `ENOTEMPTY` 오류
943</h3>948</h3>
944 949
945기존 설치에 대해 `npm install -g @anthropic-ai/claude-code`를 실행하면 npm이 이전 패키지 디렉토리를 옆으로 이동하는 동안 실패할 수 있습니다:950기존 설치에 대해 `npm install -g @anthropic-ai/claude-code`를 실행하면 npm이 이전 패키지 디렉토리를 옆으로 이동하는 동안 실패할 수 있습니다.
946 951
947```text theme={null}952```text theme={null}
948npm error code ENOTEMPTY953npm error code ENOTEMPTY
953npm error ENOTEMPTY: directory not empty, rename '...'958npm error ENOTEMPTY: directory not empty, rename '...'
954```959```
955 960
956`npm error path` 줄은 npm이 이동할 수 없는 디렉토리의 이름을 지정합니다. 해당 디렉토리와 옆에 있는 모든 남은 `.claude-code-*` 디렉토리를 삭제하세요. 이전 중단된 실행은 뒤에 남길 수 있습니다. 아래 명령은 `npm root -g`로 전역 패키지 디렉토리를 찾습니다. `npm error path` 줄이 이름을 지정하는 디렉토리가 `npm root -g`가 인쇄하는 디렉토리 아래에 없으면(예: nvm으로 Node 버전을 전환했기 때문에) 오류가 이름을 지정하는 디렉토리를 대신 삭제하세요:961`npm error path` 줄은 npm이 이동할 수 없는 디렉토리의 이름을 지정합니다. 해당 디렉토리와 옆에 있는 모든 `.claude-code-*` 디렉토리를 삭제합니다. 이전 중단된 실행이 남길 수 있습니다. 아래 명령은 `npm root -g`로 전역 패키지 디렉토리를 찾습니다. `npm error path` 줄이 이름을 지정하는 디렉토리가 `npm root -g`가 출력하는 디렉토리 아래에 없으면(예: nvm으로 Node 버전을 전환했기 때문에) 오류가 이름을 지정하는 디렉토리를 대신 삭제합니다.
957 962
958<Tabs>963<Tabs>
959 <Tab title="macOS/Linux">964 <Tab title="macOS/Linux">
961 rm -rf "$(npm root -g)/@anthropic-ai/claude-code"966 rm -rf "$(npm root -g)/@anthropic-ai/claude-code"
962 ```967 ```
963 968
964 그런 다음 남은 임시 디렉토리를 제거하세요. zsh가 `no matches found`를 인쇄하면 제거할 것이 없었습니다:969 그런 다음 남은 임시 디렉토리를 제거합니다. Zsh가 `no matches found`를 출력하면 제거할 것이 없었습니다.
965 970
966 ```bash theme={null}971 ```bash theme={null}
967 rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*972 rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*
975 </Tab>980 </Tab>
976</Tabs>981</Tabs>
977 982
978그런 다음 다시 설치하세요:983그런 다음 다시 설치합니다.
979 984
980```bash theme={null}985```bash theme={null}
981npm install -g @anthropic-ai/claude-code986npm install -g @anthropic-ai/claude-code
982```987```
983 988
984`claude --version`으로 확인하세요. 이는 `2.1.211 (Claude Code)`와 같은 버전 번호를 인쇄합니다.989`claude --version`으로 확인합니다. 이는 `2.1.211 (Claude Code)`와 같은 버전 번호를 출력합니다.
985 990
986<h2 id="login-and-authentication">991<h2 id="login-and-authentication">
987 로그인 및 인증992 로그인 및 인증
