GitHub 프로젝트를 로컬 PC에서 실행하기 (Windows 중심)

 

💻 GitHub 프로젝트를 로컬 PC에서 실행하기 (Windows 중심)

이 글은 Windows 사용자를 위한 실행 가이드입니다. 세 단계로 빠르게 끝냅니다.

요약(3단계)

1. 소스코드 가져오기 (GitHub → PC)
2. 프로그램 실행 준비 (Python 라이브러리 설치)
3. (선택) 아두이노 연동 준비 (Arduino CLI 설치)

Linux 사용자는 패키지 이름만 다르고 흐름은 동일합니다(아래에 짧게 언급).

🔎 목차

• 1. 소스코드 가져오기
• 2. Python 의존성 설치
• 3. (선택) Arduino CLI 설치 및 PATH 등록
• 4. 프로그램 실행
• ※ Linux 한 줄 안내

---

1️⃣ 소스코드 가져오기 (PC에 다운로드)

두 가지 방법이 있지만, git clone 방식을 추천합니다.

방법 1: git clone 사용 (권장)

1. Git Bash 실행: 시작 메뉴에서 Git Bash 검색·실행
2. 작업 폴더로 이동 (예: E 드라이브)

   cd /e

3. 저장소 복제 (GitHub의 초록색 <> Code 버튼에서 URL 복사)
   Git Bash 붙여넣기 단축키: Shift + Insert

   git clone <저장소_URL>

4. 프로젝트 폴더로 이동 (예: z_Codex_01)

   cd z_Codex_01

방법 2: ZIP 파일로 다운로드

1. GitHub에서 <> Code → Download ZIP
2. 원하는 위치에 압축 해제
3. Git Bash 또는 cmd로 해당 폴더로 이동
   주의: 경로에 한글/공백이 많으면 도구에 따라 문제가 생길 수 있습니다.

---

2️⃣ Python 의존성 설치

이 프로젝트는 PySide6 라이브러리를 사용합니다.

1. (아직 설치 전이라면) Python 설치 시 “Add Python to PATH” 체크
2. 프로젝트 폴더(z_Codex_01)에서 다음 실행:

   pip install PySide6

pip이 안 된다면? Python 미설치이거나 PATH 미체크일 가능성이 큽니다. Python을 재설치하며 “Add Python to PATH”를 꼭 체크하세요.

---

3️⃣ (선택) Arduino CLI 설치 및 PATH 등록

아두이노 보드에 명령줄로 컴파일/업로드하려면 필요합니다(프로그램이 내부적으로 호출).

1. Arduino CLI Releases에서 Windows용 ZIP 다운로드
2. 압축 해제 후 arduino-cli.exe를 예: C:\Program Files\Arduino CLI로 이동
3. PATH 등록 (Win+R → sysdm.cpl → 고급 탭 → 환경 변수 → 시스템 변수 Path 편집 → 새로 만들기):

   C:\Program Files\Arduino CLI

4. 모든 터미널을 닫고 새 창에서 설치 확인:

   arduino-cli version

---

▶ 4️⃣ 프로그램 실행

프로젝트 루트(z_Codex_01)에서 다음 명령을 실행합니다.

python -m backend.main

backend/main.py를 메인 엔트리로 실행합니다.

---

※ Linux 한 줄 안내

Linux는 배포판에 따라 apt 또는 dnf로 git, python3, pip를 설치한 뒤, 위와 동일하게 pip install PySide6 → python -m backend.main 순서로 진행합니다.

ⓒ 2025 AI교육연구회 withseok. All rights reserved. (위드석) · 상업적 이용금지 · 위드석 · AI교육연구회