> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 설치

> npm으로 Octoparse CLI를 설치하고 Node.js 및 플랫폼 요구 사항을 확인한 후 로컬 엔진, Chrome 및 사용자 브라우저 준비 상태를 검증하세요.

Octoparse CLI는 npm 패키지로 배포되며 Node.js 20 이상에서 실행됩니다.

## 요구 사항

Octoparse CLI를 설치하기 전에 환경에 다음 항목이 있는지 확인하세요.

* Node.js 20 이상
* npm 8 이상
* 터미널 또는 명령줄 셸

Node.js와 npm 버전을 확인합니다.

```bash theme={null}
node -v
npm -v
```

Node.js 버전이 20보다 낮으면 계속하기 전에 업그레이드하세요.

<Card title="Node.js 다운로드" href="https://nodejs.org/">운영 체제에 맞는 Node.js 20 이상을 설치하세요.</Card>

### 로컬 추출 지원 플랫폼

로컬 추출은 독립 Chrome 런타임을 사용합니다. 지원 플랫폼은 다음과 같습니다.

* macOS(x64 및 arm64)
* Windows(x64)
* Linux(x64)

<Warning>Linux arm64는 로컬 추출을 지원하지 않습니다. Chrome for Testing은 Linux arm64 패키지를 제공하지 않습니다. ARM 서버 또는 Linux arm64 이미지가 있는 Apple Silicon 컨테이너에서는 로컬 `run` 및 `detect` 명령이 실패합니다. 클라우드 추출(`octoparse cloud start`)은 모든 플랫폼에서 작동합니다.</Warning>

## npm으로 설치

Octoparse CLI를 전역으로 설치합니다.

```bash theme={null}
npm install -g @octoparse-ai/octoparse-cli
```

설치 후 `octoparse` 명령을 전역에서 사용할 수 있습니다.

## 설치 확인

### 빠른 확인

설치된 버전을 확인합니다.

```bash theme={null}
octoparse --version
```

도움말 출력을 엽니다.

```bash theme={null}
octoparse --help
```

### doctor 출력 이해

진단을 실행합니다.

```bash theme={null}
octoparse doctor
```

`octoparse doctor`는 Node.js, 내장 Octoparse 엔진, 런타임 확장 프로그램, Chrome 가용성 및 브라우저 모드를 확인합니다.

성공하면 `"ok": true`가 반환됩니다.

```json theme={null}
{
  "ok": true,
  "checks": [
    { "name": "node", "ok": true, "message": "v24.0.0" },
    { "name": "engine", "ok": true, "message": "..." },
    { "name": "electron-client", "ok": true, "message": "not required" },
    { "name": "browser-mode", "ok": true, "message": "independent Chrome only" }
  ]
}
```

* `electron-client: not required` — CLI 실행에는 Octoparse 데스크톱 앱이 필요하지 않습니다.
* `browser-mode: independent Chrome only` — 로컬 추출은 데스크톱 클라이언트 브라우저가 아니라 독립 Chrome 런타임을 사용합니다.

`chrome`에 `ok: false`가 표시되면 아래 [문제 해결](#문제-해결)을 참고하세요.

필요한 경우 사용자 지정 Chrome 경로를 사용합니다.

```bash theme={null}
octoparse doctor --chrome-path /path/to/chrome
```

### 사용자 브라우저 준비 상태 확인

```bash theme={null}
octoparse browser status
```

구조화된 환경 및 사용자 브라우저 확인에는 JSON 출력을 사용하세요.

```bash theme={null}
octoparse doctor --json
octoparse browser status --json
```

## 설치 관리

### Octoparse CLI 업데이트

npm 설치 명령을 다시 실행해 업데이트합니다.

```bash theme={null}
npm install -g @octoparse-ai/octoparse-cli
octoparse --version
```

### Octoparse CLI 제거

```bash theme={null}
npm uninstall -g @octoparse-ai/octoparse-cli
```

셸에서 `octoparse: command not found`를 반환하면 명령이 제거된 것입니다.

## 문제 해결

| 문제                             | 확인할 사항                                                                                                                                                   |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `octoparse: command not found` | npm 전역 바이너리 디렉터리가 `PATH`에 포함되어 있는지 확인하세요.                                                                                                                |
| 설치 중 권한 오류                     | npm 전역 패키지 권한을 확인하거나 Node.js 버전 관리자를 사용하세요. [npm 가이드 보기 →](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) |
| Node.js 버전이 너무 오래됨             | Node.js 20 이상으로 업그레이드하세요.                                                                                                                                |
| npm 설치 타임아웃                    | npm 레지스트리, 프록시, VPN 또는 방화벽 설정을 확인하세요.                                                                                                                    |
| Chrome 다운로드 실패                 | Chrome for Testing CDN 네트워크 액세스를 확인하세요. 로컬에 설치된 Chrome은 `--chrome-path`로 지정할 수 있습니다.                                                                     |
| Linux arm64 미지원                | Linux x64 환경을 사용하거나 `octoparse cloud start`로 클라우드 추출을 사용하세요.                                                                                             |
| `doctor` 확인 실패                 | 표시된 종속성(Node.js, Chrome, 엔진 파일)을 수정한 후 `octoparse doctor`를 다시 실행하세요. 문제가 계속되면 `ok: false` 출력을 Octoparse 지원팀에 전달하세요.                                      |

## 다음 단계

<CardGroup cols={3}>
  <Card title="API 키 발급 및 로그인" href="/docs/ko/cli/quick-start/get-api-key-and-log-in">Octoparse API 키를 생성하고 CLI를 인증합니다.</Card>
  <Card title="첫 작업 실행" href="/docs/ko/cli/quick-start/run-your-first-task">작업을 나열하고 확인한 뒤 로컬에서 실행하고 데이터를 내보냅니다.</Card>
  <Card title="모든 명령 보기" href="../reference/command-cheatsheet">작업, 로컬 실행, 클라우드 실행 및 내보내기를 위한 일반적인 CLI 명령을 검토합니다.</Card>
</CardGroup>