Ultralytics YOLO27: 대기자 명단에 등록하세요.
Get Started
첫 YOLO 모델 학습하기·설정·레슨 1/10
강의초급

Ultralytics 설치

깨끗한 환경에 Ultralytics를 설치하고, yolo checks 보고서에서 디바이스를 확인한 다음, 예측을 한 번 실행하여 설정이 올바른지 확인합니다.

수확기, 트럭, 트랙터, 관개 장비가 보이고 각각 라벨이 지정된 Ultralytics YOLO 탐지 상자로 표시된 농경지 항공 사진

CPU로 조용히 대체되어 실행되는 학습 작업은 한 시간이 아니라 하루가 걸릴 수 있으며, 너무 늦을 때까지 알아차리지 못할 수 있습니다. 설치가 잘못된 경우에도 같은 문제가 발생합니다. 강의 중간에 import 오류가 발생하거나 GPU가 표시되지 않을 수 있습니다.

여기서 10분을 투자하면 두 문제를 모두 예방할 수 있습니다. 새 환경에 ultralytics 패키지를 설치하고, yolo checks 보고서를 한 줄씩 읽은 다음, 모든 구성 요소가 연결되었음을 확인하는 첫 YOLO26 예측을 실행합니다.

학습 성과

깨끗한 환경에 Ultralytics를 설치하고 yolo checks의 한 줄만 보고도 CUDA, MPS, CPU 중 어떤 환경에서 실행될지 알 수 있습니다.

속성 과정
이미 사용법을 알고 계신다면, 간단히 요약해 드리겠습니다.

  1. Python 3.10 이상으로 새 가상 환경을 만들고 활성화합니다.

  2. NVIDIA 머신에서는 먼저 CUDA PyTorch를 설치한 다음 pip install ultralytics을 설치합니다.

  3. yolo checks을 실행하고 첫 번째 줄 끝부분에 표시된 디바이스를 확인합니다.

  4. yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg을 실행하고 저장된 이미지를 엽니다.

실습형

깨끗한 환경 만들기#

ultralytics 패키지는 Python 3.8 이상에 설치할 수 있지만, 최신 PyTorch 릴리스에는 Python 3.10 이상이 필요합니다. 따라서 3.12와 같은 최신 버전으로 새 프로젝트를 시작하세요. 새 가상 환경을 사용하면 패키지와 종속성이 다른 프로젝트에 영향을 주지 않습니다.

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
python --version                 # 3.10 or newer

Ultralytics 빠른 시작 가이드에서는 Conda 또는 Docker를 선호하는 경우 동일한 설정 방법을 안내합니다.

올바른 PyTorch를 설치한 다음 Ultralytics 설치하기#

OS, 패키지 관리자, 언어, 컴퓨팅 플랫폼을 선택하여 알맞은 pip install 명령을 생성하는 PyTorch "Start Locally" 선택기

Ultralytics는 PyTorch에서 실행되며, PyTorch가 설치되어 있지 않으면 pip가 기본 PyTorch 빌드를 설치합니다. 이 기본 설정이 "왜 CPU를 사용하고 있지?"라는 문제의 주요 원인이므로 먼저 빌드를 선택하세요.

사용 중인 머신먼저 수행할 작업그다음
NVIDIA GPU드라이버와 일치하는 CUDA 빌드를 PyTorch 선택기에서 설치합니다.pip install ultralytics이 설치를 처리합니다.
Apple Silicon Mac별도 작업 불필요: 기본 빌드에 MPS가 포함되어 있습니다.pip install ultralytics
CPU만 사용별도 작업 불필요pip install ultralytics
pip install ultralytics

이 명령 하나로 ultralytics Python 패키지, yolo 명령줄 도구, 그리고 OpenCV 및 NumPy와 같은 종속성이 설치됩니다.

yolo checks 보고서 읽기#

yolo checks은 Ultralytics가 사용할 버전과 하드웨어를 출력합니다. MacBook에서 얻은 실제 출력을 간추린 내용입니다.

Ultralytics 8.4.175 🚀 Python-3.12.12 torch-2.14.1 CPU (Apple M5 Pro)
Setup complete ✅ (18 CPUs, 48.0 GB RAM, 594.4/926.3 GB disk)

OS                     macOS-27.0.1-arm64-arm-64bit
Python                 3.12.12
Install                pip
GPU                    None

각 줄의 의미:

  1. Ultralytics 8.4.175 ... torch-2.14.1: 패키지와 PyTorch 버전입니다. 버그를 보고할 때 이 정보를 인용하세요.
  2. CPU (Apple M5 Pro): device을 전달하지 않았을 때 사용하는 디바이스입니다. 가장 중요한 줄입니다.
  3. Setup complete ✅: 설치 상태가 정상입니다.
  4. GPU None: PyTorch에서 CUDA GPU를 찾지 못했습니다. Mac에서는 예상되는 결과지만, NVIDIA 머신에서는 문제입니다.

첫 번째 줄에 표시된 디바이스에 따라 조치하세요.

이 과정에는 GPU가 필요하지 않습니다. 모든 예제는 노트북 CPU에서 몇 분 안에 완료되도록 구성되어 있습니다. 전체 규모로 학습할 때는 GPU가 중요하며, 이 경우 속도가 10배 이상 빨라지는 경우가 많습니다.

예측 한 번으로 확인하기#

예측은 전체 스택을 실행합니다. YOLO26 나노 가중치를 다운로드하고, 이미지를 가져와 모델을 실행한 다음, 주석이 추가된 사본을 저장합니다.

yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg
image 1/1 bus.jpg: 640x480 4 persons, 1 bus, 20.1ms
Speed: 0.7ms preprocess, 20.1ms inference, 0.5ms postprocess per image at shape (1, 3, 640, 480)
Results saved to runs/detect/predict
  • 640x480 4 persons, 1 bus: 모델에 맞게 이미지 크기를 640×480으로 조정했으며, 객체 5개를 찾았습니다.
  • 20.1ms: 이 CPU에서의 추론 시간입니다. 값을 기록해 두세요. 첫 번째 속도 기준값입니다.
  • runs/detect/predict: 주석이 추가된 bus.jpg의 저장 위치입니다. 명령을 다시 실행하면 predict-2가 생성됩니다. Ultralytics는 이전 실행 결과를 덮어쓰지 않습니다.

이 명령의 기본값인 신뢰도, 이미지 크기, 저장 위치는 모두 구성 참조에 나와 있습니다.

일반적인 문제 해결하기#

모르는 사이에 CPU로 학습하기

증상: NVIDIA GPU가 있는 컴퓨터에서 yolo checks에 CPU 및 GPU None가 표시되고 학습이 지나치게 느립니다. 원인: pip가 CPU 전용 PyTorch를 설치했습니다. 해결: torch 및 torchvision를 제거하고 PyTorch selector에서 CUDA 빌드를 설치한 뒤, 첫 줄에 CUDA:0이 표시될 때까지 yolo checks을 다시 실행합니다.

yolo: 명령을 찾을 수 없습니다

원인: 이 터미널에서 가상 환경이 활성화되지 않아 yolo 스크립트가 PATH에 없습니다. 해결: 새 터미널을 열 때마다 yolo을 사용하기 전에 source .venv/bin/activate(또는 Windows에 해당하는 명령)를 실행합니다.

증상원인해결 방법
requirements: ... not found, attempting AutoUpdate 다음에 No module named pip을 실행합니다.pip가 없는 환경을 만들었기 때문에 Ultralytics가 추가 패키지를 자동 설치할 수 없습니다.환경의 도구를 사용하여 지정된 패키지를 설치합니다(예: uv pip install lap).
가중치 또는 데이터셋 다운로드 시간 초과네트워크에서 GitHub 릴리스 에셋을 차단합니다.다른 위치에서 yolo26n.pt을 한 번 다운로드한 다음 로컬 경로를 전달합니다.
PermissionError에서 runs/을 기록합니다.작업 디렉터리가 읽기 전용입니다.쓰기 가능한 프로젝트 폴더에 cd을 저장합니다.

그 밖의 문제는 일반적인 문제 가이드에서 알려진 해결 방법을 확인할 수 있으며, Ultralytics 저장소의 종료된 이슈에 답이 있는 경우가 많습니다. 새 이슈를 등록하기 전에 해당 내용을 검색해 보세요.

사용해 보기

새 환경에 Ultralytics를 설치하고 yolo checks을 실행한 다음 버스 예측을 실행합니다. 세 줄로 구성된 설정 기록을 제출하세요. Ultralytics 및 PyTorch 버전, yolo checks의 첫 번째 줄에 표시된 디바이스(NVIDIA 머신에서는 CUDA:0라고 표시되는지에 대한 증거 포함), 그리고 bus.jpg에 보고된 추론 시간을 기록합니다.

완료 조건
다음 조건을 모두 충족하면 레슨을 완료한 것입니다.

  • yolo checks이 Setup complete ✅로 완료되고 예상한 디바이스를 표시합니다.

  • 사람 4명과 버스 1대가 박스로 표시된 runs/detect/predict/bus.jpg이 생성됩니다.

  • 버전, 디바이스, bus.jpg 추론 시간을 기록했습니다.

정답 보기
python -m venv .venv
source .venv/bin/activate
# NVIDIA only: install the CUDA PyTorch build from pytorch.org first
pip install ultralytics
yolo checks
yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg
Versions: Ultralytics 8.4.175, torch 2.14.1
Device:   CPU (Apple M5 Pro); use device=mps for the Apple GPU
bus.jpg:  20.1 ms inference at 640x480

노트북 CPU에서 bus.jpg은 약 10~60ms가 걸리고, 최신 NVIDIA GPU에서는 몇 ms가 걸릴 것으로 예상됩니다. yolo checks에 잘못된 디바이스가 표시되면 다음 단계로 넘어가기 전에 PyTorch를 수정하세요.

다음 단계

환경이 정상적으로 작동합니다. 다음으로 Python에서 동일한 예측을 실행하고 모델이 반환하는 각 필드를 읽는 방법을 알아보세요.

진행 상황을 저장하려면 로그인하세요