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

# PyTorch (CUDA)

PyTorch는 AI(인공지능)와 딥러닝 모델을 만들고 학습시키는 데 사용하는 Python 라이브러리입니다. 전 세계적으로 가장 많이 사용되는 딥러닝 프레임워크 중 하나입니다.

CUDA는 NVIDIA GPU를 활용하여 연산 속도를 크게 높여주는 기술입니다. PyTorch에 CUDA를 연결하면 AI 모델의 학습과 추론 속도가 CPU만 사용할 때보다 수십 배 빨라집니다.

## 사전 준비

이 가이드를 따라하기 전에 아래 항목이 모두 준비되어 있어야 합니다.

| 항목               | 설명                                    | 확인 방법                            |
| ---------------- | ------------------------------------- | -------------------------------- |
| **NVIDIA GPU**   | RTX 3060, 4070 등 NVIDIA 그래픽카드가 장착된 PC | 장치 관리자에서 "디스플레이 어댑터" 확인          |
| **NVIDIA 드라이버**  | GPU를 사용하기 위한 드라이버 소프트웨어               | PowerShell에서 `nvidia-smi` 입력     |
| **CUDA Toolkit** | GPU 연산을 위한 NVIDIA 개발 도구               | PowerShell에서 `nvcc --version` 입력 |
| **uv + Python**  | Python 패키지 매니저 (이전 가이드 참고)            | PowerShell에서 `uv --version` 입력   |
| **가상환경 활성화**     | Python 가상환경이 활성화된 상태                  | 프롬프트 앞에 `(프로젝트이름)` 표시 확인         |

<Warning>
  NVIDIA GPU가 없는 PC(Intel 내장 그래픽, AMD GPU만 있는 경우)에서는 CUDA를 사용할 수 없습니다. 이 경우 PyTorch의 CPU 버전만 사용할 수 있습니다.
</Warning>

<Steps>
  <Step title="PyTorch CUDA 버전 설치하기">
    가상환경이 활성화된 상태에서(프롬프트 앞에 `(test)` 같은 표시가 있어야 합니다) 아래 명령어를 입력하고 Enter를 누르세요.

    ```powershell theme={null}
    uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130
    ```

    <img src="https://mintcdn.com/ddok/u-wdFw6DcFUUAg_e/images/environment-setup/windows/pytorch-cuda/01-pip-install-torch-cu130.png?fit=max&auto=format&n=u-wdFw6DcFUUAg_e&q=85&s=202ddc9b6f06fe3ab506131b4032bb9d" alt="uv pip install torch torchvision --index-url cu130 실행" width="1115" height="628" data-path="images/environment-setup/windows/pytorch-cuda/01-pip-install-torch-cu130.png" />

    이 명령어가 하는 일을 설명하면:

    * `uv pip install` - uv를 사용하여 Python 패키지를 설치합니다
    * `torch` - PyTorch 본체입니다
    * `torchvision` - 이미지 처리에 특화된 PyTorch 확장 라이브러리입니다
    * `--index-url https://download.pytorch.org/whl/cu130` - CUDA 13.0용 PyTorch를 다운로드할 저장소 주소를 지정합니다. 이 옵션이 없으면 GPU를 사용할 수 없는 CPU 전용 버전이 설치될 수 있습니다.

    <Note>
      PyTorch 파일 크기가 약 2\~3GB로 매우 크기 때문에, 인터넷 속도에 따라 설치에 수 분에서 수십 분이 걸릴 수 있습니다. 다운로드 중에 터미널을 닫지 마세요.
    </Note>

    <Tip>
      `cu130`은 CUDA 13.0 버전을 의미합니다. 본인의 CUDA Toolkit 버전에 맞는 것을 선택해야 합니다. CUDA 버전은 `nvcc --version` 명령어로 확인할 수 있습니다. 만약 CUDA 12.6을 사용 중이라면 `cu126`으로 변경합니다.
    </Tip>
  </Step>

  <Step title="CUDA 사용 가능 여부 확인하기">
    설치가 완료되면 CUDA 정상 작동 여부를 확인합니다. 아래 명령어를 입력합니다.

    ```powershell theme={null}
    uv run python -c "import torch; print(torch.cuda.is_available())"
    ```

    이 명령어는 Python을 실행하여 PyTorch의 CUDA 사용 가능 여부를 확인합니다.

    ### 결과가 `False`인 경우

    NVIDIA 드라이버가 설치되지 않았거나, CUDA Toolkit이 올바르게 구성되지 않은 경우 `False`가 출력됩니다. 경고 메시지(UserWarning: cudaGetDeviceCount() returned cudaErrorNotSupported)가 함께 나타날 수도 있습니다.

    <img src="https://mintcdn.com/ddok/u-wdFw6DcFUUAg_e/images/environment-setup/windows/pytorch-cuda/02-cuda-available-false.png?fit=max&auto=format&n=u-wdFw6DcFUUAg_e&q=85&s=ce44000f83fa0bc53891b8244e53e9e0" alt="torch.cuda.is_available() 결과 False (드라이버 미설치 상태)" width="1115" height="628" data-path="images/environment-setup/windows/pytorch-cuda/02-cuda-available-false.png" />

    <Warning>
      `False`가 나온다면 아래 "문제 해결" 섹션을 확인합니다. NVIDIA 드라이버와 CUDA Toolkit을 설치한 후 다시 시도해야 합니다.
    </Warning>

    ### 결과가 `True`인 경우

    NVIDIA 드라이버와 CUDA Toolkit이 올바르게 설치된 상태에서는 `True`가 출력됩니다.

    <img src="https://mintcdn.com/ddok/u-wdFw6DcFUUAg_e/images/environment-setup/windows/pytorch-cuda/03-cuda-available-true.png?fit=max&auto=format&n=u-wdFw6DcFUUAg_e&q=85&s=765fb74ed06884913dbab5a00cb1c85d" alt="torch.cuda.is_available() 결과 True (드라이버 설치 후 정상 작동)" width="1115" height="628" data-path="images/environment-setup/windows/pytorch-cuda/03-cuda-available-true.png" />

    `True`가 출력되면 PyTorch에서 GPU 가속을 정상적으로 사용할 수 있습니다.
  </Step>
</Steps>

## GPU 사용 방법 (간단 예시)

CUDA가 정상 동작하는 것을 확인했다면, Python 코드에서 다음과 같이 GPU를 활용할 수 있습니다.

```python theme={null}
import torch

# GPU가 사용 가능하면 GPU를, 아니면 CPU를 사용합니다
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print(f"사용 중인 장치: {device}")

# 텐서(데이터)를 GPU로 옮기기
x = torch.randn(3, 3).to(device)
print(x)
```

<Tip>
  `.to('cuda')` 또는 `.to(device)`를 사용하면 데이터와 모델을 GPU 메모리로 옮겨서 빠르게 연산할 수 있습니다.
</Tip>

## 문제 해결

`torch.cuda.is_available()`이 `False`를 반환하는 경우 아래 항목을 확인합니다.

| 확인 항목               | 확인 방법                                                | 해결 방법                                                                       |
| ------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------- |
| **NVIDIA 드라이버**     | PowerShell에서 `nvidia-smi` 실행                         | [NVIDIA 드라이버 다운로드](https://www.nvidia.com/Download/index.aspx)에서 최신 드라이버 설치 |
| **CUDA Toolkit 버전** | `nvcc --version`으로 확인                                | 설치한 CUDA 버전과 PyTorch의 cu 버전이 일치하는지 확인                                       |
| **PyTorch 버전**      | `python -c "import torch; print(torch.__version__)"` | 버전에 `+cu130` 같은 CUDA 표시가 있는지 확인. 없으면 CPU 전용 버전입니다                           |
| **GPU 메모리 부족**      | `nvidia-smi`에서 메모리 사용량 확인                            | 다른 GPU 사용 프로그램을 종료합니다                                                       |

## 설치 점검 목록

* 관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다.
* 설치 후 버전 확인 명령어(`--version`)를 실행해 정상 설치를 검증했습니다.
* PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다.
* 문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: Rancher Desktop 설치 가이드" icon="arrow-right" href="/setup/windows/rancher-desktop">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>