마음에 드는 오픈소스를 발견해서 초록색 Code 버튼까지 눌렀는데, 압축을 풀고 나니 낯선 폴더와 파일만 잔뜩 펼쳐지는 순간이 있어요. README를 열어봐도 npm install부터 하라는데 그 명령을 어디에 쳐야 하는지부터 막히죠. 답부터 말하면, 깃허브 코드 실행은 언제나 같은 5단계예요. 코드 가져오기 → README로 언어 확인 → 런타임 설치 → 의존성 설치 → 실행 명령. 이 순서만 머리에 넣으면 프로젝트가 파이썬이든 Node.js든 대응할 수 있고, 중간에 나는 오류도 대부분 이 다섯 칸 중 어디가 비었는지의 문제예요. 아래에서 각 단계의 실제 명령어와, 비전공자가 유독 자주 걸려 넘어지는 지점을 순서대로 풀어볼게요.

• 깃허브 코드 실행, 결론부터 말하면 이 5단계
• 코드를 내 컴퓨터로 가져오는 3가지 방법
• README에서 반드시 확인할 4줄
• 실행 환경 설치와 윈도우·맥 명령어 차이
• 언어별 실행 명령어 정리 (파이썬·Node.js·자바)
• 자주 만나는 오류 7가지와 해결법
• Claude Code에 물어보면 빨라지는 지점
• 설치 없이 브라우저에서 실행하기
• 이럴 땐 어떻게? 상황별 Q&A
• 참고자료

깃허브 코드 실행, 결론부터 말하면 이 5단계

깃허브 저장소는 완성된 프로그램이 아니에요. 요리로 치면 레시피와 재료 목록만 들어 있는 상자에 가깝죠. 그래서 압축을 풀자마자 더블클릭해서 실행되는 파일을 찾으면 안 나와요. 재료(런타임)를 부엌에 들여놓고, 레시피가 부르는 부재료(의존성)를 장 봐 와야 비로소 조리 명령이 통합니다.

이 구조를 이해하면 왜 같은 오류가 반복되는지도 보여요. 파이썬 프로젝트를 받아놓고 파이썬을 설치하지 않으면 python: command not found가 뜨고, 파이썬은 깔았는데 pip install -r requirements.txt를 안 돌렸으면 ModuleNotFoundError가 떠요. 오류 문구는 달라도 원인은 결국 빠뜨린 단계를 알려주는 신호예요.

단계별로 예상 소요 시간도 미리 알아두면 마음이 편해요. 코드 받기는 1분, 런타임 설치는 처음이라면 5~15분, 의존성 설치는 프로젝트 규모에 따라 30초에서 5분 정도 걸려요. 두 번째 프로젝트부터는 런타임이 이미 깔려 있으니 전체가 3분 안에 끝나는 일도 흔해요.

코드를 내 컴퓨터로 가져오는 3가지 방법

코드를 받는 방법은 크게 세 가지예요. 어느 쪽을 골라도 폴더 안 내용물은 같지만, 나중에 원본이 업데이트됐을 때 따라가기 쉬운 정도가 달라요.

가장 간단한 건 ZIP 다운로드예요. 저장소 상단의 초록색 Code 버튼을 누르면 드롭다운이 열리고, 맨 아래 Download ZIP 항목이 있어요. 받은 파일의 압축을 풀면 폴더 이름 끝에 -main이 붙어 있는데 그대로 둬도 실행에는 문제없어요.

두 번째는 git clone이에요. 같은 Code 버튼 안의 HTTPS 탭에 있는 주소를 복사한 뒤 터미널에서 이렇게 칩니다.

# 코드를 내려받을 상위 폴더로 이동 (예: 바탕화면)
cd Desktop
저장소 전체를 현재 위치에 복제
git clone https://github.com/사용자명/저장소명.git
만들어진 폴더 안으로 들어가기
cd 저장소명

세 번째는 GitHub Desktop 같은 그래픽 프로그램이에요. 명령어 없이 버튼 클릭으로 클론과 업데이트를 할 수 있어서, 터미널 자체가 부담스러운 단계라면 시작점으로 괜찮아요. 다만 실행 명령은 결국 터미널에서 쳐야 하니 완전히 피할 수는 없어요.

저장소 전체가 아니라 특정 폴더·파일만 받고 싶다면

파일 하나만 필요할 때는 깃허브에서 그 파일을 연 뒤 Raw 버튼을 눌러 나오는 주소를 저장하면 돼요. 브라우저에서 우클릭 후 다른 이름으로 저장하면 그 파일만 떨어집니다.

폴더 단위로 골라 받으려면 sparse checkout을 써요. 수백 메가짜리 모노레포에서 예제 폴더 하나만 필요할 때 유용해요.

# 파일 내용 없이 저장소 뼈대만 먼저 가져오기
git clone --filter=blob:none --sparse https://github.com/사용자명/저장소명.git
cd 저장소명
필요한 폴더만 지정해서 내려받기
git sparse-checkout set examples/basic

README에서 반드시 확인할 4줄

README는 길지만 실행에 필요한 정보는 보통 네 가지예요. 요구 버전, 설치 명령, 실행 명령, 환경변수. 이 네 개만 찾아 메모장에 옮겨 적고 시작하면 삽질이 확 줄어요.

요구 버전은 Node.js 18 이상, Python 3.10+ 같은 형태로 Requirements나 Prerequisites 항목에 적혀 있어요. 여기를 무시하고 훨씬 낮은 버전으로 돌리면 설치 중간에 알 수 없는 오류가 쏟아지는데, 원인이 버전이라는 걸 알아채기까지 시간이 오래 걸려요.

환경변수도 놓치기 쉬운 항목이에요. .env.example이나 .env.sample 파일이 보이면 그걸 복사해서 .env로 이름을 바꾸고, 안에 적힌 API 키 자리를 채워야 해요. 이걸 안 하면 실행은 되는데 화면이 비거나 401 오류가 뜹니다.

README가 부실한 저장소도 많아요. 그럴 땐 폴더 안 파일 이름으로 언어를 판별하면 돼요. 설정 파일이 곧 언어의 지문이거든요.

실행 환경 설치와 윈도우·맥 명령어 차이

런타임은 그 언어로 쓰인 코드를 해석해 주는 프로그램이에요. 파이썬 코드는 파이썬이, 자바스크립트 코드는 Node.js가 있어야 돌아가요. 설치는 각 공식 홈페이지에서 설치 파일을 받아 다음 버튼을 누르는 정도로 끝나는데, 윈도우에서는 설치 중 Add to PATH 같은 체크박스를 꼭 켜야 해요. 이걸 놓치면 나중에 명령어를 못 찾는다는 오류가 납니다.

설치가 끝났으면 터미널을 새로 열어 확인해요. 이미 열려 있던 터미널은 설치 사실을 모르기 때문에, 반드시 창을 닫았다가 다시 열어야 해요. 이 한 가지를 몰라서 설치를 두세 번 반복하는 경우가 정말 많아요.

# 설치 확인 (버전 번호가 뜨면 성공)
git --version
node -v
npm -v
python --version

운영체제에 따라 달라지는 명령도 있어요. 특히 파이썬 가상환경 활성화 명령과 경로 구분자가 다른데, 블로그 글을 따라 하다 막히는 이유의 절반은 여기에 있어요.

VS Code로 폴더 열고 터미널 띄우기

터미널에서 cd로 폴더를 찾아 들어가는 게 번거롭다면 VS Code를 쓰는 게 훨씬 편해요. 파일 메뉴의 폴더 열기로 클론한 폴더를 선택하면, 그 안에서 터미널을 열었을 때 이미 프로젝트 폴더에 들어와 있는 상태가 돼요.

터미널은 상단 메뉴의 터미널 → 새 터미널로 열거나 백틱 단축키로 열 수 있어요. 여기서 npm install을 치면 지금 열어둔 폴더 기준으로 실행되니 경로 때문에 헤맬 일이 없어요.

언어별 실행 명령어 정리 (파이썬·Node.js·자바)

여기서부터는 프로젝트 종류별로 갈라져요. 앞에서 설정 파일로 언어를 판별했다면, 해당하는 블록만 따라 하면 됩니다.

파이썬 프로젝트

파이썬은 가상환경을 먼저 만드는 게 정석이에요. 가상환경은 이 프로젝트 전용 라이브러리 창고라고 생각하면 돼요. 안 만들고 설치하면 컴퓨터 전체 파이썬에 라이브러리가 섞여서, 다른 프로젝트를 돌릴 때 버전이 충돌해요.

# 1. 프로젝트 폴더 안에 가상환경 생성
python -m venv venv
2. 활성화 (맥·리눅스)
source venv/bin/activate
2. 활성화 (윈도우 PowerShell)
venv\Scripts\activate
3. 필요한 라이브러리 한 번에 설치
pip install -r requirements.txt
4. 실행 (파일명은 프로젝트마다 다름)
python main.py

활성화가 됐는지는 터미널 프롬프트 맨 앞에 (venv)가 붙었는지로 확인해요. 이게 안 보이면 활성화가 안 된 상태라 설치가 엉뚱한 곳으로 갑니다. 작업이 끝나면 deactivate로 빠져나오면 돼요.

Node.js 프로젝트

Node는 가상환경 개념이 없고, 설치하면 프로젝트 폴더 안에 node_modules 폴더가 생겨요. 이 폴더는 수천 개 파일이 들어가 무거우니 절대 직접 건드리지 마세요.

# 1. 의존성 설치 (package.json 기준)
npm install
2. 개발 서버 실행
npm run dev
프로젝트에 따라 아래일 수도 있어요
npm start

실행하면 터미널에 Local: http://localhost:3000 같은 주소가 떠요. 이 주소를 브라우저 주소창에 직접 입력해야 화면이 보여요. 터미널만 보고 아무 일도 안 일어난다고 생각해 닫아버리는 경우가 흔한데, 서버는 터미널이 켜져 있는 동안만 살아 있어요. 종료는 Ctrl+C예요.

자바 프로젝트

자바는 JDK를 설치한 뒤, Maven이면 mvn spring-boot:run이나 mvn package로, Gradle이면 ./gradlew bootRun 형태로 돌려요. 빌드 도구가 알아서 의존성을 받아오기 때문에 첫 실행은 몇 분 걸릴 수 있어요.

자주 만나는 오류 7가지와 해결법

오류 메시지는 무서워 보이지만 사실 친절한 편이에요. 영어 한 줄에 원인이 거의 다 담겨 있거든요. 아래는 깃허브 코드 실행 중 가장 자주 마주치는 일곱 가지예요.

표에서 해결책을 찾지 못했다면 오류 메시지의 맨 마지막 줄을 그대로 검색하는 게 가장 빨라요. 터미널에는 여러 줄이 쏟아지지만 실제 원인은 보통 맨 아래 한 줄에 요약돼 있어요. 파일 경로나 개인 정보가 섞여 있으면 그 부분만 지우고 검색하면 됩니다.

설치가 꼬였다는 느낌이 들 때는 초기화도 방법이에요. Node 프로젝트라면 node_modules 폴더와 package-lock.json을 지우고 npm install을 다시 돌리면 웬만한 문제는 정리돼요. 파이썬이라면 venv 폴더를 통째로 지우고 다시 만들면 돼요. 두 경우 모두 지워도 원본 코드는 그대로니 겁낼 필요 없어요.

Claude Code에 물어보면 빨라지는 지점

여기까지가 표준 절차인데, 현실은 저장소마다 조금씩 달라요. 그래서 AI 코딩 도구를 옆에 두고 진행하면 막히는 시간이 크게 줄어요. 특히 Claude Code처럼 터미널에서 폴더 전체를 읽을 수 있는 도구는, README를 대신 읽고 이 프로젝트에 맞는 명령을 알려줄 수 있어요.

효과가 가장 큰 건 오류 대응이에요. 터미널에 뜬 붉은 글씨를 통째로 복사해 붙여넣고 무슨 뜻이고 뭘 하면 되는지 물어보면, 검색으로 파편화된 글 여러 개를 뒤지는 것보다 훨씬 빠르게 다음 행동이 정해져요.

실제로 쓸 만한 프롬프트는 이런 형태예요.

• 이 폴더를 읽고 어떤 언어 프로젝트인지, 실행하려면 어떤 순서로 명령을 쳐야 하는지 알려줘. 내 운영체제는 윈도우야.
• 다음은 npm run dev 실행 중 나온 오류 전문이야. 원인과 해결 순서를 단계로 알려줘. (오류 붙여넣기)
• README에 환경변수 설명이 있는데 무슨 값을 넣어야 하는지 모르겠어. .env.example을 보고 각 항목이 무슨 용도인지 설명해줘.

질문할 때 운영체제와 현재 상태를 함께 적는 게 핵심이에요. 맥과 윈도우는 명령이 다르기 때문에, 이걸 빼면 맞지 않는 명령을 받아 또 막히게 돼요.

설치 없이 브라우저에서 실행하기

내 컴퓨터에 아무것도 깔기 싫거나, 회사 노트북이라 설치 권한이 없을 때도 방법이 있어요. 클라우드 개발 환경을 쓰면 브라우저 안에서 코드 편집기와 터미널이 함께 열리고, 실행까지 거기서 끝나요.

깃허브 자체에서 제공하는 Codespaces는 저장소 페이지의 Code 버튼 안 Codespaces 탭에서 바로 만들 수 있어요. 컨테이너 설정 파일이 있는 프로젝트라면 필요한 런타임과 의존성까지 자동으로 준비된 상태로 열려요. Gitpod도 비슷한 방식으로 저장소 주소 기반으로 환경을 띄워줘요.

둘 다 무료 사용량이 있고 그 이상은 과금되는 구조인데, 무료 한도와 요금은 정책이 바뀌니 깃허브 공식 요금 안내 페이지에서 확인하는 게 정확해요. 가볍게 코드를 훑어보거나 몇 분만 돌려보는 용도라면 무료 범위 안에서 충분한 경우가 많아요.

다만 장기적으로는 로컬 환경을 한 번 갖춰두는 쪽이 이득이에요. 한 번 설치해두면 이후 모든 프로젝트에서 재사용되고, 인터넷 없이도 작업할 수 있으니까요. 클라우드 환경은 급할 때 쓰는 우회로 정도로 생각하면 좋아요.

이럴 땐 어떻게? 상황별 Q&A

ZIP으로 받아 압축까지 풀었는데 실행할 파일이 안 보여요

정상이에요. 깃허브 저장소에는 실행 파일이 아니라 소스 코드가 들어 있어서, 의존성 설치와 실행 명령을 거쳐야 비로소 동작해요. 폴더 안에 package.json이 있으면 npm install 후 npm run dev, requirements.txt가 있으면 pip install -r requirements.txt 후 python main.py 순서로 진행하세요.

npm install은 성공했는데 npm run dev에서 스크립트가 없다고 나와요

package.json의 scripts 항목을 열어 실제 이름을 확인하면 해결돼요. 프로젝트마다 dev 대신 start, serve, watch 같은 이름을 쓰기 때문이에요. npm run만 입력하면 사용 가능한 스크립트 목록이 출력되니 거기서 골라 쓰면 됩니다.

서버가 실행됐다는데 브라우저에 아무것도 안 떠요

터미널에 출력된 주소를 정확히 확인하세요. 포트 번호가 3000이 아니라 5173이나 8000일 수 있고, 다른 프로그램이 그 포트를 쓰고 있으면 프로젝트가 자동으로 다른 번호로 바꿔 띄우기도 해요. 또 터미널 창을 닫으면 서버도 함께 꺼지니, 브라우저를 볼 동안 터미널은 켜둔 상태로 두세요.

저장소가 너무 커서 클론이 오래 걸려요

최신 상태만 필요하다면 이력을 빼고 받으면 훨씬 빨라요. git clone --depth 1 저장소주소로 최근 커밋 하나만 가져오면 되고, 특정 폴더만 필요하면 앞서 설명한 sparse checkout을 쓰면 됩니다. 단순 참고용이면 ZIP 다운로드가 제일 간단해요.

남의 코드를 내 프로젝트에 가져다 써도 되나요

저장소의 LICENSE 파일을 먼저 확인해야 해요. MIT나 Apache 2.0처럼 허용 범위가 넓은 라이선스는 출처 표기 조건을 지키면 상업적 이용도 가능하지만, 조건이 까다로운 라이선스도 있어요. 라이선스 파일이 아예 없다면 기본적으로 모든 권리가 원작자에게 있다고 보고, 이슈나 연락처로 문의하는 게 안전해요.

참고자료

• GitHub 공식 문서 시작하기 — 저장소 클론, 기본 개념을 한국어로 정리한 공식 안내
• Git 공식 다운로드 — 운영체제별 Git 설치 파일과 설치 안내
• Node.js 공식 홈페이지 — 지원 버전과 설치 파일 확인
• Python 공식 다운로드 — 버전별 설치 파일과 설치 시 PATH 옵션 안내

깃허브 코드 실행이 어렵게 느껴지는 이유는 명령어가 복잡해서가 아니라, 저장소 안에 든 게 완성품이 아니라 재료라는 걸 아무도 먼저 알려주지 않기 때문이에요. 코드 받기, 언어 확인, 런타임 설치, 의존성 설치, 실행 명령. 이 다섯 칸을 체크리스트처럼 놓고 하나씩 채워가면 처음 보는 저장소라도 길을 잃지 않아요. 오류가 나면 당황하지 말고 메시지 마지막 줄을 읽으세요. 거기에 빠뜨린 칸의 번호가 적혀 있어요. 그래도 막히면 오류 전문을 그대로 AI 도구에 붙여넣어 다음 한 걸음만 물어보는 방식을 권합니다. 첫 프로젝트는 30분이 걸려도, 두 번째부터는 같은 순서가 몸에 붙어 몇 분이면 끝나요.

함께 보면 좋은 글

• “커밋을 잘못했어요” 깃 사용법, 비전공자가 실제로 친 명령어 순서대로
• 터미널 기초, 30분이면 달라지는 Claude Code 첫 실행 준비
• 깃허브 블로그 만들기, 1시간이면 내 주소가 생겨요: Claude Code로 첫 글 발행까지