[파이썬 기초] VSCode로 파이썬 앱 개발 시작하기: 입문자용 환경 세팅부터 유튜브 다운로더 프로그램 만들기 (pip, uv, venv, yt-dlp 완벽 정리)

 안녕하세요! 오늘은 비전공자나 개발 초보자도 막힘없이 따라 할 수 있는 VSCode(Visual Studio Code) 기반의 파이썬(Python) 앱 개발 환경 세팅 가이드를 준비했습니다.

단순히 이론만 공부하는 것이 아니라, 내가 원하는 유튜브 영상을 자동으로 다운로드하고 MP3 음원 파일로 추출하는 실전 '유튜브 다운로더 프로그램'까지 함께 만들어볼 예정입니다.

개발 공부를 하면서 직접 겪은 시행착오와 각종 오류 메시지 해결 방법(Node.js, FFmpeg 설치 등)까지 아주 상세하게 기록해 두었으니, 이 글을 끝까지 보시면서 천천히 따라와 주세요!

[파이썬 기초] VSCode로 파이썬 앱 개발 시작하기:
입문자용 환경 세팅부터 유튜브 다운로더 프로그램 만들기
(pip, uv, venv, yt-dlp 완벽 정리)

1. 파이썬(Python) 설치 및 환경 변수(Path) 설정

가장 먼저 우리 컴퓨터가 파이썬 코드를 이해하고 실행할 수 있도록 파이썬 해석기를 설치해야 합니다.

1) 파이썬 다운로드 및 설치 단계

1. 파이썬 공식 웹사이트(Python.org)에 접속합니다.

2. 상단 메뉴에서 Downloads에 마우스를 올린 뒤, 본인의 운영체제(Windows 등)를 선택합니다.

3. 노란색 다운로드 버튼을 클릭하여 설치 파일을 받습니다.

4. 다운로드된 .exe 설치 파일을 실행합니다.

⚠️ [가장 중요] 설치 시 필수 체크 사항! 설치 창이 뜨면 가장 아래쪽에 있는 "Add python.exe to PATH" (또는 Add Python to environment variables) 체크박스에 반드시 체크를 해주셔야 합니다. 이 설정을 누락하면 나중에 터미널에서 파이썬 명령어를 전혀 인식하지 못해 심각한 문제가 생깁니다. 이후 과정은 모두 "예(Next)" 또는 **"Install Now"**를 눌러 기본값으로 설치를 완료합니다.

2) 정상 설치 확인하기

설치가 완료되었다면 컴퓨터의 터미널(명령 프롬프트 또는 PowerShell)을 열고 아래 명령어를 입력하여 버전이 정상적으로 출력되는지 확인합니다.

python --version 

Python 3.12.x와 같이 버전 숫자가 명확하게 나타난다면 파이썬이 내 컴퓨터에 안전하게 안착한 것입니다. 

2. VSCode 설치 및 파이썬 확장 프로그램 세팅

코드 작성을 편리하게 도와주는 최고의 코드 에디터인 VSCode(Visual Studio Code)를 활용해 보겠습니다.

1) Microsoft 공식 Python 확장 프로그램 설치

VSCode를 실행한 뒤, 파이썬 개발을 원활하게 하려면 전용 도구를 설치해야 합니다.

1. VSCode 왼쪽 세로줄 메뉴에서 블록 모양 아이콘인 Extensions(확장 프로그램, 단축키: Ctrl + Shift + X)을 클릭합니다.

2. 검색창에 "Python"을 입력합니다.

3. Microsoft에서 공식 제공하는 Python 항목을 찾아 [Install(설치)] 버튼을 누릅니다.

💡 이 확장 프로그램이 왜 필요할까요? 코드 작성 시 오타를 잡아주는 린팅(Linting), 코드를 자동으로 완성해 주는 자동완성(IntelliSense), 그리고 코드의 오류를 추적해 주는 디버깅(Debugging) 기능을 제공하므로 초보자에게는 나침반 같은 필수 존재입니다.

3. 작업 폴더 생성 및 VSCode 터미널 진입 방법 (3가지 루트)

이제 내 컴퓨터 안에 파이썬 프로젝트를 진행할 전용 폴더를 하나 만들어야 합니다. 예시로 D:\init\파이썬폴더명 공간을 기준으로 설명해 드릴게요. 폴더를 만든 후 VSCode에서 터미널을 열고 진입하는 방법은 크게 3가지가 있습니다. 편한 방법을 선택해 보세요.

• 방법 1: 왼쪽 폴더 리스트 활용

  • VSCode에서 해당 폴더를 연 상태(File -> Open Folder)라면, 왼쪽 폴더 리스트 빈 공간에 마우스 우클릭을 한 뒤 [Open in Integrated Terminal(통합 터미널에서 열기)]을 선택합니다.

• 방법 2: 빈 화면 우클릭 및 경로 이동

  • VSCode 빈 화면에서 우클릭 후 터미널을 실행합니다. 그 후 직접 cd 파이썬폴더명 명령어를 입력해 해당 폴더 안으로 진입합니다.

• 방법 3: 윈도우 탐색기 우클릭 활용

  • 내 컴퓨터 탐색기에서 생성한 파이썬 폴더 안으로 직접 들어갑니다. 빈 곳에 마우스 우클릭을 한 뒤 [가져오기/터미널에서 열기] 또는 [Code로 열기(Open with Code)]를 실행해 줍니다.

4. 파이썬 패키지 매니저 비교 및 가상환경(venv) 세팅

파이썬으로 앱을 개발할 때는 다른 사람들이 미리 만들어 둔 '라이브러리(패키지)'를 가져와서 사용하게 됩니다. 이때 패키지를 관리해 주는 도구를 패키지 매니저라고 합니다.

가장 대중적인 pip 방식과 최근 초보자들 사이에서 간단명료한 스타일로 각광받는 고성능 매니저 uv 방식을 비교 정리해 드릴게요.

1) 차세대 고성능 매니저: uv 사용법

uv는 Rust 언어로 작성되어 기존 매니저들을 압도하는 엄청난 속도를 자랑합니다. 통합 프로젝트 관리 기능이 우수하고 디스크 공간을 효율적으로 아껴줍니다.

• 설치 명령어: pip install uv

• 버전 체크: uv --version

• 가상환경 생성: uv venv

• 프로젝트 초기화: uv init

• 패키지 설치 및 의존성 추가: uv add 패키지명 (실행 시 자동으로 pyproject.toml 파일과 uv.lock 파일이 업데이트되어 관리가 편리해집니다.)

• 패키지 독립 설치: uv pip install 패키지명

• 스크립트 바로 실행: uv run 파일명.py

2) 파이썬 기본 탑재 매니저: pip 사용법

별도의 설치 없이 파이썬을 깔면 자동으로 내장되어 있는 기본 매니저입니다.

• 버전 체크: pip --version

• pip 업그레이드 명령어: python -m pip install --upgrade pip

  *일부 PC나 강의 환경에 따라 그냥 `pip install --upgrade pip`로 실행하면 
  오류가 나는 경우가 있습니다. 그럴 때는 당황하지 말고 
  앞에 `python -m`을 붙여서 실행하면 완벽하게 성공할 수 있습니다.*
  
  

💡 잠깐! 가상환경(venv)은 왜 필수로 만들어야 할까요?

가상환경은 프로젝트별로 방을 따로 나누는 독립된 환경 공간입니다. 우리가 만들 앱마다 필요한 서브 프로그램(라이브러리)의 버전이 다를 수 있습니다. 만약 가상환경을 쓰지 않고 컴퓨터 전체 공간에 설치해 버리면, 다른 프로그램을 만들 때 버전 충돌이 일어나 전체 코드가 망가질 수 있으므로 반드시 프로젝트 폴더마다 독립적인 가상환경을 만들어 주어야 합니다.

[기본 pip 방식] 가상환경 설정 및 활성화 명령어

내가 작업할 폴더 위치로 터미널 경로를 맞춘 뒤 아래 명령어를 차례로 입력합니다.

• 가상환경 생성: python -m venv venv

• 가상환경 활성화 (운영체제별 다름):

• Windows (방법 1): venv\Scripts\activate

• Windows (방법 2): .\.venv\Scripts\activate

• macOS / Linux: source venv/bin/activate

5. [돌발 상황] 가상환경 위치를 잘못 잡았을 때 해결 방법

초보 시절에 가장 자주 하는 실수 중 하나가 터미널 경로를 엉뚱한 곳에 두고 가상환경(venv) 명령어를 입력하는 것입니다. 경로가 꼬였다면 과감하게 지우고 새로 만드는 것이 가장 깔끔합니다.

1) 잘못 생성된 venv 폴더 강제 삭제

터미널에서 아래 명령어를 입력해 잘못 만들어진 폴더를 삭제합니다 (경로는 예시입니다).

rm -r D:\init\venv

2) 올바른 파이썬 프로젝트 폴더로 이동 후 가상환경 재생성

cd D:\init\파이썬폴더명

uv venv

이렇게 차근차근 순서대로 이동 후 생성해 주면, 내가 지정한 파이썬 전용 작업 폴더 내부에 올바르고 깔끔하게 가상환경이 구축됩니다.

6. 실전! 유튜브 다운로더 프로그램 만들기

환경 세팅이 끝났으니 이제 진짜 작동하는 앱을 개발해 볼 차례입니다. 유튜브 다운로드 라이브러리 중 가장 강력하고 업데이트가 활발한 yt-dlp를 이용해 보겠습니다.

1 단계: 가상환경 활성화 상태에서 라이브러리 설치

터미널 앞에 가상환경 이름이 표시되어 있는지 확인한 후, 아래 명령어를 입력해 다운로더 핵심 라이브러리를 설치합니다. (uv 사용자 기준)

uv pip install yt-dlp

2 단계: downloader.py 파일 생성 및 코드 작성

VSCode에서 내가 작업 중인 폴더 안에 downloader.py라는 새 파일을 만들고 아래 코드를 그대로 복사해서 붙여넣은 뒤 저장(Ctrl + S)합니다.

import yt_dlp

def download_video(url) :

    options = {

        'format' :  'best',  # 가장 좋은 화질 선택

        'outtmpl' :  '%(title)s.%(ext)s' ,  # 영상 제목을 파일명으로 설정
    }

    
    with yt_dlp.YoutubeDL(options) as ydl :

        ydl.download([url])

url = input("유튜브 URL을 입력하세요: ")

download_video(url)

3 단계: 프로그램 실행 및 결과 확인

터미널 창에 아래 명령어를 입력하여 프로그램을 가동합니다.

python downloader.py

실행하면 터미널 화면에 유튜브 URL을 입력하세요: 라는 안내 문구가 뜹니다. 

이때 다운로드하고 싶은 유튜브 영상 주소를 복사해서 터미널에 붙여넣고 엔터(Enter)를 누릅니다.

다운로드가 완료되면 VSCode 왼쪽 폴더 리스트에 방금 다운로드한 따끈따끈한 영상 파일(.mp4 등)이 들어온 것을 볼 수 있습니다!

❓ 당황하지 마세요! (음성 미출력 관련 팁)

VSCode 자체 내부 플레이어로 영상을 클릭해 재생하면 간혹 소리(음성)가 안 들려서 당황할 수 있습니다. 이것은 에디터 자체 내장 플레이어의 한계 때문입니다. 윈도우 탐색기로 해당 폴더에 들어가 곰플레이어, 윈도우 미디어 플레이어 등 일반 동영상 재생 프로그램으로 실행해 보시면 소리와 영상 모두 아주 정상적으로 출력되는 것을 확인할 수 있습니다.

7. [오류 해결] WARNING: No supported JavaScript runtime found 메시지 조치법

유튜브 영상을 다운로드하다 보면 터미널 창에 아래와 같은 길고 무시무시한 경고(WARNING) 메시지가 뜰 때가 있습니다.

WARNING: [youtube] No supported JavaScript runtime could be found. Only deno is enabled by default; to use another runtime add --js-runtimes RUNTIME[:PATH] to your command/config. YouTube extraction without a JS runtime has been deprecated, and some formats may be missing.

🧐 원인 분석

이 오류는 내 컴퓨터에 유튜브 자바스크립트 코드를 해석해 줄 Node.js 가 설치되어 있지 않아서 발생합니다. 이 상태로 그냥 두면 일부 유튜브 영상의 경우 화질 옵션이 누락되거나 추출 과정에서 튕기는 오류가 발생할 수 있습니다.

🛠️ 해결 방법: Node.js 설치하기

1. Node.js 공식 사이트(https://nodejs.org)에 접속합니다.

2. 왼쪽 버튼에 있는 안정적인 LTS 버전을 클릭하여 설치 프로그램을 다운로드한 뒤 실행합니다. (모두 Next를 눌러 설치 완료)

3. 설치가 끝났다면 VSCode 터미널을 완전히 종료했다가 다시 새로 켜 줍니다. (매우 중요!)

4. 새 터미널 창에서 아래 명령어를 입력해 정상 설치되었는지 검증합니다.

5. node --version

6. 터미널에 v20.x.x 같은 버전 숫자가 정상적으로 찍힌다면 경고 메시지 해결 완료입니다! 이제 다시 실행해 보면 경고 없이 깔끔하게 작동합니다.

8. 가상환경 경로 확인 꿀팁 및 최종 업그레이드 코드 (영상 vs MP3 음원 선택 기능)

1) 터미널 켤 때마다 체크해야 하는 필수 꿀팁

영상을 다운로드 받거나 코드를 수정할 때, 터미널 맨 앞에 붙어 있는 가상환경 접두사를 꼭 체크하는 습관을 가져야 합니다.

• 터미널 맨 앞에 (python) 이라고 뜨는 경우 -> 내 프로젝트 전용 공간이 아닌 엉뚱한 기본 가상환경이 켜진 것이므로 비정상 상태입니다.

• 터미널 맨 앞에 (py-youtube-D) 또는 (venv) 라고 정확한 폴더/환경 이름이 뜨는 경우 -> 정상 상태입니다.

• 만약 다운로드 받을 폴더 위치나 경로가 변경되었다면 반드시 가상환경(venv) 상태를 다시 재확인하고, 필요시 라이브러리를 재설치해 주어야 꼬이지 않습니다.

2) 최종 완성본: 영상 또는 MP3 음원만 쏙 골라 다운로드하는 확장 코드

유튜브에서 영상 말고 배경음악이나 교양 오디오만 MP3 파일로 저장하고 싶을 때가 많죠? 기능을 업그레이드한 최종 코드를 공유합니다. 기존 downloader.py 내용을 싹 지우고 아래 코드를 덮어씌워 보세요.

import yt_dlp

def download_video(url):
    print("\n[안내] 고화질 영상 다운로드를 시작합니다...")
    options = {
        'format': 'best',
        'outtmpl': '%(title)s.%(ext)s',
    }
    with yt_dlp.YoutubeDL(options) as ydl:
        ydl.download([url])

def download_audio(url):
    print("\n[안내] MP3 음원 추출을 시작합니다...")
    options = {
        'format': 'bestaudio/best',
        'outtmpl': '%(title)s.%(ext)s',
        'postprocessors': [{
            'key': 'FFmpegExtractAudio',
            'preferredcodec': 'mp3',      # mp3 확장자로 지정
            'preferredquality': '192',    # 음질 192kbps 설정
        }],
    }
    with yt_dlp.YoutubeDL(options) as ydl:
        ydl.download([url])

# 프로그램 실행부
url = input("유튜브 URL을 입력하세요: ")
print("\n--- 모드 선택 ---")
print("1. 영상 다운로드 (.mp4)")
print("2. 음원 다운로드 (.mp3)")
choice = input("\n선택하세요 (1 또는 2 입력): ")

if choice == '1':
    download_video(url)
elif choice == '2':
    download_audio(url)
else:
    print("잘못된 입력이에요! 1번이나 2번을 입력해 주세요.")

🚨 필수 주의사항: 음원(MP3) 추출을 위해서는 FFmpeg이 필수입니다!

위 코드에서 2번(음원 다운로드) 기능을 온전하게 사용하려면 컴퓨터가 미디어 파일을 상호 변환할 수 있도록 돕는 FFmpeg이라는 프로그램이 설치되어 있어야 합니다. 이게 없으면 변환 단계에서 에러가 납니다.

Windows 사용자라면 터미널 창에 아래 명령어를 입력해 초간단 패키지 매니저(Chocolatey 등) 혹은 수동 설치를 통해 구성해 주어야 합니다.

# Chocolatey 매니저가 설치되어 있는 경우의 초간단 명령어
choco install ffmpeg

# 설치 완료 후 검증 명령어
ffmpeg -version

버전 정보가 정상적으로 노출된다면 이제 영상은 물론, 고음질의 MP3 파일까지 내 손으로 직접 만든 파이썬 프로그램을 통해 자유롭게 추출할 수 있게 됩니다!

9. 마치며 & 요약

오늘 공부한 내용을 요약해 보겠습니다.

단계	핵심 작업 내용	주의 사항 및 팁
1단계	파이썬 설치	설치 창에서 Add python.exe to PATH 무조건 체크하기
2단계	VSCode 세팅	Microsoft 공식 Python 확장 프로그램 설치로 자동완성 활성화
3단계	가상환경 구축	uv venv 또는 python -m venv venv로 독립된 방 만들기
4단계	기능 구현	yt-dlp 라이브러리로 유튜브 링크 분석 및 파일 저장
5단계	트러블 슈팅	JavaScript 경고 메시지는 Node.js 설치로 깔끔하게 해결!

처음에는 터미널 창에 영어 명령어들을 입력하는 게 어색하고 어렵게 느껴질 수 있지만, 직접 손으로 타이핑하고 에러 메시지를 하나씩 정복해 나가다 보면 나만의 멋진 앱 개발에 금방 익숙해질 것입니다.

열공하세요!