> For the complete documentation index, see [llms.txt](https://orbitron.gitbook.io/orbitron-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://orbitron.gitbook.io/orbitron-docs/documentation/ko/user-guide/installation/manual-path-setup.md).

# PATH 수동 설정

Orbitron 설치 시 PATH 자동 설정이 실패한 경우, 아래 가이드를 따라 수동으로 설정할 수 있습니다.

## 왜 PATH 설정이 필요한가요?

Orbitron은 `~/.local/bin/` 디렉토리에 설치됩니다. 터미널에서 `orbitron` 명령어를 바로 사용하려면 이 경로가 시스템 PATH에 등록되어 있어야 합니다.

PATH 설정이 되어 있지 않으면:

* `orbitron` 명령어를 찾을 수 없다는 오류가 발생합니다
* 매번 전체 경로(`~/.local/bin/orbitron`)를 입력해야 합니다
* 이전 버전이 다른 경로에 있다면 그 버전이 실행될 수 있습니다

***

## macOS / Linux

### Zsh (macOS 기본 셸)

1. **설정 파일 열기:**

```bash
nano ~/.zshrc
```

2. **파일 맨 위에 다음 줄 추가:**

```bash
export PATH="$HOME/.local/bin:$PATH"
```

3. **저장 후 종료:** `Ctrl + O` → `Enter` → `Ctrl + X`
4. **설정 적용:**

```bash
source ~/.zshrc
```

5. **설치 확인:**

```bash
orbitron --version
```

### Bash

1. **설정 파일 열기:**

```bash
nano ~/.bashrc
```

> **참고:** macOS에서 Bash를 사용하는 경우 `~/.bash_profile`을 대신 수정하세요.

2. **파일 맨 위에 다음 줄 추가:**

```bash
export PATH="$HOME/.local/bin:$PATH"
```

3. **저장 후 종료:** `Ctrl + O` → `Enter` → `Ctrl + X`
4. **설정 적용:**

```bash
source ~/.bashrc
```

5. **설치 확인:**

```bash
orbitron --version
```

### Fish

1. **설정 파일 열기:**

```bash
nano ~/.config/fish/config.fish
```

2. **다음 줄 추가:**

```fish
fish_add_path $HOME/.local/bin
```

3. **저장 후 종료:** `Ctrl + O` → `Enter` → `Ctrl + X`
4. **새 터미널 열기** (권장) 또는:

```fish
source $HOME/.config/fish/config.fish
```

5. **설치 확인:**

```bash
orbitron --version
```

### Sh / Ash (Alpine Linux 등)

1. **설정 파일 열기:**

```bash
nano ~/.profile
```

2. **다음 줄 추가:**

```bash
export PATH="$HOME/.local/bin:$PATH"
```

3. **저장 후 종료:** `Ctrl + O` → `Enter` → `Ctrl + X`
4. **설정 적용:**

```bash
. ~/.profile
```

5. **설치 확인:**

```bash
orbitron --version
```

***

## Windows

### 방법 1: 시스템 설정에서 PATH 추가 (권장)

1. `Win + R` 키를 눌러 실행 창 열기
2. `sysdm.cpl` 입력 후 `Enter`
3. **고급** 탭 → **환경 변수** 클릭
4. **사용자 변수**에서 `Path` 선택 → **편집** 클릭
5. **새로 만들기** 클릭 후 다음 경로 추가:

```
%USERPROFILE%\.local\bin
```

6. **확인** 버튼을 눌러 모든 창 닫기
7. 새 PowerShell 또는 명령 프롬프트 창 열기
8. **설치 확인:**

```powershell
orbitron --version
```

### 방법 2: PowerShell 프로필 수정

1. **PowerShell에서 프로필 파일 열기:**

```powershell
notepad $PROFILE
```

> **참고:** 파일이 없다는 오류가 나면 먼저 생성:
>
> ```powershell
> New-Item -Path $PROFILE -ItemType File -Force
> notepad $PROFILE
> ```

2. **메모장에서 다음 줄 추가:**

```powershell
$env:Path = "$env:USERPROFILE\.local\bin;" + $env:Path
```

> **참고:** 환경변수 `$env:USERPROFILE`을 사용하면 사용자명이 바뀌어도 동작합니다.

3. **저장** (`Ctrl + S`) 후 메모장 닫기
4. **프로필 다시 로드:**

```powershell
. $PROFILE
```

5. **설치 확인:**

```powershell
orbitron --version
```

### 방법 3: PowerShell 명령어로 영구 등록

관리자 권한 없이 현재 사용자에게만 PATH를 추가합니다:

```powershell
$binPath = "$env:USERPROFILE\.local\bin"
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($currentPath -notlike "*$binPath*") {
    [Environment]::SetEnvironmentVariable("Path", "$binPath;$currentPath", "User")
    Write-Host "PATH가 추가되었습니다. 새 터미널을 열어주세요."
}
```

***

## 설정 확인 방법

### PATH에 등록되었는지 확인

**macOS / Linux:**

```bash
echo $PATH | tr ':' '\n' | grep '.local/bin'
```

출력에 `/Users/사용자명/.local/bin` 또는 `/home/사용자명/.local/bin`이 포함되어야 합니다.

> **참고:** `grep local`만 사용하면 `/usr/local/bin` 등도 매칭될 수 있습니다.

**Windows (PowerShell):**

```powershell
$env:Path -split ';' | Where-Object { $_ -like '*\.local\bin*' }
```

### Orbitron 실행 경로 확인

**macOS / Linux:**

```bash
which orbitron
```

예상 출력: `/Users/사용자명/.local/bin/orbitron`

**Windows (PowerShell):**

```powershell
Get-Command orbitron | Select-Object Source
```

예상 출력: `C:\Users\사용자명\.local\bin\orbitron.exe`

***

## 문제 해결

### "command not found" 오류가 계속 발생하는 경우

1. **터미널을 새로 열었는지 확인**
   * `source` 명령어 대신 터미널을 완전히 닫고 다시 여세요
2. **PATH 순서 확인**
   * `~/.local/bin`이 PATH의 앞쪽에 있어야 합니다
   * 다른 경로에 이전 버전이 있다면 그 버전이 먼저 실행될 수 있습니다
3. **설정 파일이 올바른지 확인**
   * 현재 사용 중인 셸 확인: `echo $SHELL` (macOS/Linux)
   * 해당 셸의 설정 파일을 수정했는지 확인

### 이전 버전이 계속 실행되는 경우

이전 설치를 제거하세요:

**Unix/Linux/macOS:**

```bash
# 레거시 바이너리만 제거 (안전)
rm ~/.orbitron/bin/orbitron

# 빈 디렉토리도 정리 (선택사항)
rmdir ~/.orbitron/bin 2>/dev/null
rmdir ~/.orbitron 2>/dev/null

# 또는 전체 레거시 디렉토리 제거 (설정 포함 - 주의)
rm -rf ~/.orbitron

# 셸 재시작
exec $SHELL
```

**Windows:**

```powershell
# 레거시 바이너리만 제거 (안전)
Remove-Item "$env:USERPROFILE\.orbitron\bin\orbitron.exe"

# 또는 전체 레거시 디렉토리 제거 (설정 포함 - 주의)
Remove-Item -Recurse -Force "$env:USERPROFILE\.orbitron"
```

자세한 문제 해결 방법은 [문제 해결](/orbitron-docs/documentation/ko/user-guide/installation/troubleshooting.md) 페이지를 참조하세요.

***

## 관련 문서

* [설치 가이드](https://github.com/AlphaCode-AI/orbitron-docs/tree/main/docs/ko/user-guide/installation/README.md) - Orbitron 설치 방법
* [문제 해결](/orbitron-docs/documentation/ko/user-guide/installation/troubleshooting.md) - 설치 관련 문제 해결
* [마이그레이션 가이드](/orbitron-docs/documentation/ko/user-guide/installation/migration-guide.md) - 레거시 버전에서 업그레이드