Python 환경 설정 | Windows/Mac에서 Python 설치하고 시작하기

· 16분 읽기 · 수정 초급 튜토리얼
Python 환경 설정 | Windows/Mac에서 Python 설치하고 시작하기

이 글의 핵심

Python 환경 설정에 대한 실전 가이드입니다. Windows/Mac에서 Python 설치하고 시작하기 등을 예제와 함께 상세히 설명합니다.

들어가며: Python 개발 시작하기

”Python 설치가 복잡해 보여요”

Python은 설치부터 간단합니다. 이 글에서는 Windows와 Mac 모두에서 Python을 설치하고, 실전 개발 환경을 구축하는 방법을 다룹니다.

이 글에서 다루는 것:

  • Python 설치 (공식 사이트, Homebrew, pyenv 요약)
  • Python 2·3과 3.9+ 권장 이유
  • pip(Python 패키지·라이브러리 설치 도구), requirements.txt, Poetry
  • 가상환경(프로젝트마다 패키지 버전을 격리하는 독립 공간): venv, virtualenv, conda
  • IDE: VS Code, PyCharm
  • 실전 폴더 구조(src/, tests/, .gitignore)
  • 첫 Python 프로그램 실행

단위 테스트는 모든 언어에서 중요합니다. 아래에서 다루는 pytest·tests/·GitHub Actions 예제는 Node.js의 Jest, C++의 Google Test, Go의 go test, Rust의 cargo test와 개념이 같습니다. CI/CD·배포와 이어서 읽으면 Node.js GitHub Actions CI/CD와 C++ GitHub Actions 멀티 OS 빌드가 같은 그림을 보여 줍니다.

목차

  1. Python 설치
  2. 설치 채널 비교 (공식 · Homebrew · pyenv)
  3. Python 버전: 2 vs 3, 3.9+
  4. pip 사용법
  5. 가상환경 설정
  6. VS Code 설정
  7. PyCharm 설정
  8. 실전 프로젝트 구조
  9. 첫 프로그램 실행
  10. 정리

1. Python 설치

Windows에서 설치

1) Python 다운로드

python.org에서 최신 버전 다운로드합니다. Python 3.12 이상을 권장합니다.

설치 과정 상세 가이드:

  1. 다운로드: python.org에서 “Download Python 3.12.x” 버튼 클릭
  2. 설치 파일 실행: 다운로드한 .exe 파일 실행
  3. 중요: 설치 화면 하단의 “Add Python to PATH” 체크박스를 반드시 체크하세요. 이 옵션을 놓치면 명령 프롬프트에서 Python을 인식하지 못합니다.
  4. Install Now 클릭하여 기본 설정으로 설치
  5. 설치 완료: “Setup was successful” 메시지 확인

설치 확인 방법:

# 명령 프롬프트 또는 PowerShell에서 실행
python --version
# 출력: Python 3.12.0

pip --version
# 출력: pip 23.3.1 from C:\Users\YourName\AppData\Local\Programs\Python\Python312\lib\site-packages\pip (python 3.12)

python —version 명령은 설치된 Python의 버전을 확인합니다. 버전 번호가 출력되면 설치가 성공한 것입니다. pip —version은 패키지 관리자 pip의 버전과 설치 경로를 보여줍니다. 두 명령 모두 정상적으로 실행되어야 개발 환경이 제대로 구축된 것입니다.

2) PATH 수동 추가 (체크 안 했을 경우)

“Add Python to PATH”를 체크하지 않았다면, 수동으로 환경 변수를 추가해야 합니다.

# Windows 환경 변수 설정 방법
# 1. 제어판 > 시스템 및 보안 > 시스템
# 2. 왼쪽 메뉴에서 "고급 시스템 설정" 클릭
# 3. "환경 변수" 버튼 클릭
# 4. "시스템 변수" 섹션에서 "Path" 선택 후 "편집" 클릭
# 5. "새로 만들기" 클릭하여 다음 경로 추가:
#    C:\Users\YourName\AppData\Local\Programs\Python\Python312
#    C:\Users\YourName\AppData\Local\Programs\Python\Python312\Scripts

경로 확인 방법: Python 설치 폴더를 찾으려면 Windows 검색에서 “python.exe”를 검색하고, 파일 위치를 열어서 전체 경로를 복사하세요.

PATH 추가 후 확인: 명령 프롬프트를 재시작한 후 python --version을 실행하여 정상 작동하는지 확인합니다.

Mac에서 설치

방법 1: Homebrew (권장)

# Homebrew 설치 (없다면)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Python 설치
brew install python

# 확인
python3 --version
pip3 --version

brew로 설치할 때: macOS는 시스템 python3와 충돌을 피하려고 python 대신 python3 명령을 쓰는 경우가 많습니다. 팀에서 버전을 고정하려면 pyenv나 .python-version으로 맞추고, 문서에 “최소 지원 버전”을 적어 두면 온보딩이 빨라집니다.

방법 2: 공식 설치 파일

python.org에서 macOS 설치 파일 다운로드

Linux (Ubuntu/Debian)

# 시스템 업데이트
sudo apt update

# Python 설치
sudo apt install python3 python3-pip python3-venv

# 확인
python3 --version
pip3 --version

패키지 매니저 관점: apt로 깔린 python3는 배포판 스냅샷이라 버전이 낮을 수 있습니다. 서버 자동화 스크립트에서는 venv를 반드시 켜고, 전역 pip install을 남발하지 않는 것이 의존성 꼬임을 줄이는 첫걸음입니다.

2. pip 사용법

pip란?

pip(Pip Installs Packages)는 Python의 공식 패키지 관리자입니다. JavaScript의 npm, Ruby의 gem, Ubuntu의 apt와 동일한 역할을 합니다. PyPI(Python Package Index)라는 중앙 저장소에서 수십만 개의 오픈소스 라이브러리를 다운로드하고 설치할 수 있습니다.

pip가 필요한 이유:

  • 외부 라이브러리 설치: requests(HTTP 클라이언트), pandas(데이터 분석), Django(웹 프레임워크) 등
  • 의존성 관리: 라이브러리가 필요로 하는 다른 패키지를 자동으로 설치
  • 버전 관리: 프로젝트별로 다른 버전의 패키지 사용 가능

기본 명령어

# 패키지 설치 (최신 버전)
pip install requests
# 출력: Collecting requests
#       Downloading requests-2.31.0-py3-none-any.whl (62 kB)
#       Successfully installed requests-2.31.0

# 특정 버전 설치 (버전 호환성이 중요할 때)
pip install requests==2.28.0
# == : 정확히 2.28.0 버전만
# >= : 2.28.0 이상
# ~= : 2.28.x (마이너 버전만 업데이트)

# 패키지 업그레이드 (최신 버전으로 갱신)
pip install --upgrade requests
# 이미 설치된 패키지를 최신 버전으로 업데이트합니다.

# 패키지 제거
pip uninstall requests
# 확인 메시지가 나오면 'y' 입력

# 설치된 패키지 목록 확인
pip list
# 출력: Package    Version
#       ---------- -------
#       pip        23.3.1
#       requests   2.31.0
#       setuptools 68.0.0

# 패키지 상세 정보 확인 (버전, 설치 위치, 의존성)
pip show requests
# 출력: Name: requests
#       Version: 2.31.0
#       Summary: Python HTTP for Humans.
#       Home-page: https://requests.readthedocs.io
#       Location: C:\...\site-packages
#       Requires: charset-normalizer, idna, urllib3, certifi

pip install의 동작 과정:

  1. PyPI에서 패키지 검색
  2. 패키지와 의존성 다운로드
  3. 설치 위치(site-packages 폴더)에 압축 해제
  4. 패키지 메타데이터 등록

같은 패키지를 여러 번 설치하면 버전만 헷갈리기 쉽습니다. 설치 전에 pip show 패키지명으로 이미 site-packages에 있는지 확인하면 중복 설치를 줄일 수 있습니다.

requirements.txt

프로젝트 의존성을 파일로 관리:

# 현재 설치된 패키지 저장
pip freeze > requirements.txt

# requirements.txt에서 설치
pip install -r requirements.txt

requirements.txt 예시:

requests==2.28.0
flask==2.3.0
pandas==2.0.0

Poetry로 의존성·빌드 관리

**Poetry**는 pyproject.toml에 프로젝트 메타데이터와 의존성을 선언하고, 가상환경 생성·잠금 파일(poetry.lock)까지 한 번에 다루는 도구입니다. 팀에서 “pip + requirements.txt” 대신 표준화할 때 자주 씁니다.

# 설치 (공식 문서의 설치 스크립트 또는 pipx 권장)
pip install poetry

# 새 프로젝트
poetry new my-package
cd my-package

# 기존 폴더에서 초기화
poetry init

# 의존성 추가 및 설치
poetry add requests
poetry install

# 가상환경 셸 진입
poetry shell

pip / requirements.txt와 비교: pip는 유연하고 가볍습니다. Poetry는 버전 잠금과 패키징·배포까지 염두에 둔 워크플로에 맞습니다. 작은 스크립트는 venv + pip만으로 충분하고, 라이브러리·서비스 레포는 Poetry(또는 uv, pip-tools 등)를 검토하면 됩니다.

3. 가상환경 설정

가상환경이 필요한 이유

가상환경(Virtual Environment)은 프로젝트별로 독립적인 Python 환경을 만들어줍니다. 이는 Node.js의 node_modules, Ruby의 bundler와 유사한 개념입니다. 프로젝트마다 별도 주방을 두고 재료(패키지)를 보관하는 것에 가깝습니다. 한 주방의 Django 버전이 다른 프로젝트와 섞이지 않습니다.

실제 문제 시나리오:

# 문제 상황: 시스템 전역에 패키지를 설치하면
# 프로젝트 A: Django 3.0 필요 (구버전 API 사용)
# 프로젝트 B: Django 4.0 필요 (신버전 기능 사용)
# → 가상환경 없이는 두 버전을 동시에 사용할 수 없습니다!

# 해결: 각 프로젝트마다 독립적인 가상환경 생성
# project_a/venv → Django 3.0 설치
# project_b/venv → Django 4.0 설치

가상환경의 장점:

  1. 의존성 격리: 프로젝트마다 다른 버전의 패키지 사용 가능
  2. 시스템 보호: 시스템 Python을 건드리지 않아 안전
  3. 재현 가능: requirements.txt로 동일한 환경 재구축
  4. 권한 문제 해결: 관리자 권한 없이 패키지 설치 가능

venv로 가상환경 만들기

venv는 Python 3.3부터 표준 라이브러리에 포함된 가상환경 도구입니다. 별도 설치 없이 바로 사용할 수 있습니다.

1) 가상환경 생성

# Windows
python -m venv venv
# 설명: 'python -m venv'는 venv 모듈을 실행하고,
#       마지막 'venv'는 생성할 폴더 이름입니다.
#       관례적으로 'venv' 또는 '.venv'를 사용합니다.

# Mac/Linux
python3 -m venv venv
# Mac/Linux에서는 python3 명령을 사용합니다.

# 다른 이름으로 생성 가능
python -m venv myenv
python -m venv .venv  # 숨김 폴더로 생성 (관례)

생성되는 폴더 구조:

venv/
├── Scripts/           # Windows (실행 파일)
│   ├── activate.bat   # CMD용 활성화 스크립트
│   ├── Activate.ps1   # PowerShell용 활성화 스크립트
│   ├── python.exe     # 가상환경 전용 Python
│   └── pip.exe        # 가상환경 전용 pip
├── Lib/               # 패키지 설치 위치
│   └── site-packages/ # 여기에 pip install한 패키지가 저장됨
└── pyvenv.cfg         # 가상환경 설정 파일

2) 가상환경 활성화

가상환경을 활성화하면, 해당 가상환경의 Python과 pip를 사용하게 됩니다.

# Windows (PowerShell) - 가장 많이 사용
venv\Scripts\Activate.ps1

# Windows (CMD)
venv\Scripts\activate.bat

# Mac/Linux
source venv/bin/activate

활성화 확인: 프롬프트 앞에 (venv) 표시가 나타납니다.

# 활성화 전
PS C:\project>

# 활성화 후
(venv) PS C:\project>

(venv) 표시는 현재 가상환경이 활성화되어 있음을 의미합니다. 이 상태에서 pip install을 실행하면 가상환경에만 패키지가 설치되고, 시스템 Python에는 영향을 주지 않습니다.

활성화 후 확인 방법:

# 어느 Python을 사용 중인지 확인
where python  # Windows
which python  # Mac/Linux

# 출력: C:\project\venv\Scripts\python.exe
# 가상환경의 Python을 사용 중임을 확인

3) 가상환경 비활성화

작업을 마치면 가상환경을 비활성화합니다.

deactivate
# 프롬프트에서 (venv) 표시가 사라집니다.

비활성화 후: 시스템 전역 Python으로 돌아갑니다. 다시 작업하려면 activate 명령으로 재활성화하면 됩니다.

가상환경 사용 워크플로우 (실전 예제)

새 프로젝트 시작 시 표준 워크플로우:

# 1. 프로젝트 폴더 생성
mkdir my_project
cd my_project

# 2. 가상환경 생성
python -m venv venv
# 실행 시간: 약 10-30초 소요
# 생성 완료 후 venv 폴더가 생성됩니다.

# 3. 가상환경 활성화
source venv/bin/activate  # Mac/Linux
# venv\Scripts\Activate.ps1  # Windows PowerShell
# 프롬프트 앞에 (venv)가 표시되면 성공

# 4. pip 업그레이드 (권장)
pip install --upgrade pip
# 최신 버전의 pip를 사용하면 설치 속도와 안정성이 향상됩니다.

# 5. 필요한 패키지 설치
pip install flask requests
# flask: 웹 프레임워크
# requests: HTTP 클라이언트 라이브러리
# 의존성 패키지들도 자동으로 설치됩니다.

# 6. 설치된 패키지 확인
pip list
# 설치된 모든 패키지와 버전을 확인할 수 있습니다.

# 7. 의존성 파일 생성 (팀 협업 시 필수)
pip freeze > requirements.txt
# 현재 설치된 모든 패키지와 버전을 파일로 저장합니다.

# 8. 작업 완료 후 비활성화
deactivate
# 시스템 Python으로 돌아갑니다.

팀 협업 시나리오:

# 팀원 A: 프로젝트 설정
python -m venv venv
source venv/bin/activate
pip install flask==2.3.0 requests==2.31.0
pip freeze > requirements.txt
git add requirements.txt
git commit -m "Add project dependencies"
git push

# 팀원 B: 프로젝트 클론 후 동일 환경 구축
git clone https://github.com/team/project.git
cd project
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# requirements.txt에 명시된 모든 패키지가 동일 버전으로 설치됩니다.

일상적인 개발 워크플로우:

# 매일 작업 시작 시
cd my_project
source venv/bin/activate  # 가상환경 활성화

# 코드 작성 및 실행
python main.py

# 새 패키지 필요 시
pip install numpy
pip freeze > requirements.txt  # 의존성 파일 갱신

# 작업 종료 시
deactivate  # 가상환경 비활성화

virtualenv와 conda

virtualenv는 venv보다 먼저 쓰이던 도구로, 별도 패키지로 설치합니다(pip install virtualenv). Python 2·3 혼용이 필요했던 시절에 유용했고, 지금은 Python 3만 쓴다면 표준 venv가 대부분 충분합니다. 커스텀 배포나 도구 체인이 virtualenv를 요구할 때만 선택하면 됩니다.

conda(Anaconda·Miniconda·Miniforge 등)는 Python뿐 아니라 바이너리 의존성(예: 과학 계산 스택)까지 한 생태계에서 맞추고 싶을 때 강합니다.

# conda 환경 예시 (Miniconda/Anaconda 설치 후)
conda create -n myenv python=3.12
conda activate myenv
conda install numpy pandas

정리: 일반 웹·앱 개발은 **venv + pip**가 가장 흔합니다. 데이터 과학·GPU·비파이썬 라이브러리가 많으면 conda를, 레거시나 특정 도구가 요구하면 virtualenv를 고려하면 됩니다.

4. VS Code 설정

VS Code 설치

Visual Studio Code는 Microsoft에서 개발한 무료 오픈소스 코드 에디터입니다. Python 개발에 가장 많이 사용되는 도구입니다.

설치 방법:

  1. code.visualstudio.com에서 OS에 맞는 설치 파일 다운로드
  2. 설치 과정에서 “Add to PATH” 옵션 체크 (명령줄에서 code 명령 사용 가능)
  3. 설치 완료 후 VS Code 실행

Python 확장 설치

Python 개발을 위해서는 Python 확장이 필수입니다.

설치 단계:

  1. VS Code 실행
  2. Extensions 패널 열기 (단축키: Ctrl+Shift+X 또는 Cmd+Shift+X)
  3. 검색창에 “Python” 입력
  4. Microsoft 제공 “Python” 확장 설치 (다운로드 수가 가장 많은 것)
  5. 설치 완료 후 VS Code 재시작

Python 확장이 제공하는 기능:

  • IntelliSense: 코드 자동완성 (변수명, 함수명, 메서드 제안)
  • 린팅: 코드 오류 실시간 검사 (문법 오류, 스타일 위반)
  • 디버깅: 중단점 설정, 변수 검사, 단계별 실행
  • 코드 포맷팅: 자동 코드 정리 (PEP 8 스타일 가이드 준수)
  • 테스트 실행: unittest, pytest 통합

Python 인터프리터 선택

VS Code는 시스템에 설치된 여러 Python 버전 중 하나를 선택해야 합니다. 가상환경의 Python을 선택하는 것이 중요합니다.

선택 방법:

1. Ctrl+Shift+P (또는 Cmd+Shift+P) - 명령 팔레트 열기
2. "Python: Select Interpreter" 검색 및 선택
3. 목록에서 가상환경 인터프리터 선택
   예: ./venv/Scripts/python.exe (Windows)
       ./venv/bin/python (Mac/Linux)

인터프리터 선택 확인:

  • VS Code 하단 상태 표시줄에 선택된 Python 버전이 표시됩니다.
  • 예: Python 3.12.0 ('venv': venv)

자동 활성화 설정: VS Code에서 터미널을 열면 자동으로 가상환경이 활성화되도록 설정할 수 있습니다.

settings.json 설정

VS Code의 Python 개발 환경을 최적화하는 설정입니다.

설정 파일 열기:

  1. Ctrl+Shift+P → “Preferences: Open User Settings (JSON)” 검색
  2. 또는 File > Preferences > Settings → 우측 상단 파일 아이콘 클릭

권장 설정:

{
  // 린팅 (코드 검사) 활성화
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  // pylint는 코드 스타일과 잠재적 오류를 검사합니다.
  
  // 코드 포맷터 설정 (black 권장)
  "python.formatting.provider": "black",
  // black은 Python 커뮤니티에서 가장 많이 사용하는 포맷터입니다.
  
  // 저장 시 자동 포맷팅
  "editor.formatOnSave": true,
  // 파일 저장 시 자동으로 코드를 정리합니다.
  
  // 터미널에서 가상환경 자동 활성화
  "python.terminal.activateEnvironment": true,
  // VS Code 터미널을 열면 자동으로 가상환경이 활성화됩니다.
  
  // 타입 체킹 활성화 (Pylance)
  "python.analysis.typeCheckingMode": "basic",
  // 타입 힌트를 검사하여 타입 오류를 미리 발견합니다.
  
  // 자동 저장 (선택 사항)
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000
  // 1초 후 자동 저장 (코드 손실 방지)
}

black 포맷터 설치:

# 가상환경 활성화 후
pip install black

# 사용법: 파일 저장 시 자동 포맷팅
# 또는 수동 실행: Ctrl+Shift+I (Format Document)

유용한 확장 프로그램

Python 개발 생산성을 높이는 추천 확장 프로그램입니다.

필수 확장:

  • Python (Microsoft): Python 언어 지원 (필수)
  • Pylance: 고급 타입 체킹, 빠른 IntelliSense (Python 확장과 함께 자동 설치)

추천 확장:

  • autoDocstring: 함수 위에서 """ 입력 시 독스트링 템플릿 자동 생성

    def calculate_total(price, tax_rate):
    """_summary_
    
    Args:
        price (_type_): _description_
        tax_rate (_type_): _description_
    
    Returns:
        _type_: _description_
    """
    return price * (1 + tax_rate)

  • Python Test Explorer: 테스트 코드를 시각적으로 실행하고 결과 확인

  • Jupyter: Jupyter Notebook 파일(.ipynb) 지원, 데이터 분석 시 유용

  • Python Indent: 자동 들여쓰기 개선

  • Better Comments: 주석을 색상으로 구분 (TODO, FIXME 등)

확장 설치 방법:

  1. Extensions 패널 (Ctrl+Shift+X)
  2. 확장 이름 검색
  3. “Install” 버튼 클릭

확장 프로그램은 편하지만, 너무 많이 켜 두면 시작과 편집이 느려질 수 있습니다. Python·디버깅·린터처럼 당장 쓰는 것만 두고, 나머지는 필요할 때 추가하는 편이 안정적입니다.

PyCharm 설정

**PyCharm**은 JetBrains의 Python 전용 IDE입니다. 대규모 리팩터링, 디버거, 테스트·DB 도구가 한 앱에 묶여 있어 팀 단위 백엔드 개발에서 자주 쓰입니다(Community는 무료, Professional은 웹·DB 등 추가 기능).

PyCharm을 처음 열었을 때 권장되는 순서는 다음과 같습니다.

  1. PyCharm 설치 후 New Project에서 인터프리터로 가상환경을 고릅니다. Virtualenv 또는 Poetry(Poetry 프로젝트인 경우)를 선택하면 프로젝트별로 격리됩니다.
  2. Settings / Preferences → Project → Python Interpreter에서 venv 또는 시스템·conda 인터프리터를 지정합니다. VS Code의 “인터프리터 선택”과 같은 역할입니다.
  3. 코드 스타일: Editor → Code Style → Python에서 들여쓰기·줄 길이를 팀 규칙에 맞춥니다. Black·Ruff 등을 쓰면 Tools 메뉴나 File Watchers로 연동할 수 있습니다.
  4. 테스트: Run → Edit Configurations에서 pytest/unittest를 추가하거나, 테스트 파일 옆 실행 아이콘으로 실행합니다.
  5. 디버깅: 줄 번호 왼쪽에 중단점을 찍고 벌레 아이콘(Debug)으로 실행합니다. VS Code의 F5 디버깅과 개념이 같습니다.

VS Code vs PyCharm: 가볍게 여러 언어를 쓰면 VS Code, Python에 집중하고 IDE 통합 기능을 원하면 PyCharm을 고르는 식으로 선택하는 경우가 많습니다. 둘 다 프로젝트 인터프리터 = 가상환경만 맞추면 동일한 venv를 공유할 수 있습니다.

실전 프로젝트 구조: src/ · tests/ · .gitignore

협업과 배포를 위해 폴더를 나누는 방식이 널리 쓰입니다.

권장 레이아웃(요약)

my_project/
├── src/
│   └── my_package/        # 실제 패키지 코드 (이름은 프로젝트에 맞게)
│       ├── __init__.py
│       └── main.py
├── tests/
│   ├── __init__.py        # 선택
│   └── test_my_module.py
├── pyproject.toml         # Poetry·Ruff 등 사용 시
├── requirements.txt       # pip + venv만 쓸 때 의존성 고정
├── README.md
├── .gitignore
└── .venv/ 또는 venv/      # 로컬 가상환경 (저장소에 올리지 않음)
  • src/: import 경로를 명확히 하려고 소스 루트를 src 아래에 두는 방식입니다(pip install -e . 편집 가능 설치와 함께 쓰는 경우가 많음).
  • tests/: pytest·unittest 테스트를 모아 두면 CI에서 pytest tests/ 한 번에 실행하기 좋습니다.
  • .gitignore: 가상환경(venv/, .venv/), __pycache__/, .env, IDE 폴더(.idea/, 선택적 .vscode/) 등을 제외해 저장소를 깨끗이 유지합니다.

아래 예제 3: 프로젝트 구조 예시의 setup.sh / setup.ps1와 함께 보면 온보딩이 수월합니다.

5. 첫 Python 프로그램 실행

Python 코드를 실행하는 방법은 크게 세 가지입니다. 각 방법은 상황에 따라 장단점이 있습니다.

방법 1: 인터랙티브 모드 (REPL)

REPL(Read-Eval-Print Loop)은 코드를 한 줄씩 입력하고 즉시 결과를 확인할 수 있는 대화형 모드입니다. 간단한 테스트나 실험에 유용합니다.

# 터미널에서 python 명령 실행
python
# Python 3.12.0 (main, ...) [GCC ...] on linux
# Type "help", "copyright", "credits" or "license" for more information.
>>> 

# 코드 입력 및 즉시 실행
>>> print("Hello, Python!")
Hello, Python!

# 수식 계산
>>> 1 + 2
3

# 변수 선언
>>> name = "홍길동"
>>> print(name)
홍길동

# 함수 정의 (여러 줄 입력)
>>> def greet(name):
...     return f"안녕하세요, {name}님!"
...
>>> greet("철수")
'안녕하세요, 철수님!'

# 종료
>>> exit()
# 또는 Ctrl+D (Mac/Linux), Ctrl+Z (Windows)

인터랙티브 모드 활용 시나리오:

  • 간단한 계산기로 사용
  • 함수나 라이브러리 동작 테스트
  • 문법 실험 (예: 리스트 컴프리헨션 동작 확인)
  • 패키지 import 테스트

방법 2: 스크립트 파일 실행

실제 프로그램은 .py 파일로 작성하여 실행합니다. 코드를 저장하고 재사용할 수 있습니다.

hello.py 작성:

# hello.py - 첫 번째 Python 프로그램

# 기본 출력
print("Hello, Python!")
print("=" * 40)  # 구분선 출력

# 시스템 정보 확인
import sys
print(f"Python 버전: {sys.version}")
print(f"실행 경로: {sys.executable}")

# 변수와 f-string (포맷팅된 문자열)
name = "홍길동"
age = 25
city = "서울"

print(f"이름: {name}, 나이: {age}세, 거주지: {city}")

# 간단한 계산
numbers = [1, 2, 3, 4, 5]
total = sum(numbers)
average = total / len(numbers)

print(f"숫자 목록: {numbers}")
print(f"합계: {total}, 평균: {average}")

# 조건문 예제
if age >= 20:
    print(f"{name}님은 성인입니다.")
else:
    print(f"{name}님은 미성년자입니다.")

실행 방법:

# 터미널에서 실행
python hello.py

# 출력:
# Hello, Python!
# ========================================
# Python 버전: 3.12.0 (main, Oct  2 2023, 13:45:54) [GCC 11.4.0]
# 실행 경로: C:\project\venv\Scripts\python.exe
# 이름: 홍길동, 나이: 25세, 거주지: 서울
# 숫자 목록: [1, 2, 3, 4, 5]
# 합계: 15, 평균: 3.0
# 홍길동님은 성인입니다.

스크립트 실행 시 주의사항:

  • 파일 이름에 공백이나 한글이 있으면 따옴표로 감싸세요: python "내 스크립트.py"
  • 가상환경이 활성화된 상태에서 실행하세요 (패키지 의존성)
  • 현재 디렉토리에 파일이 있는지 확인: ls (Mac/Linux) 또는 dir (Windows)

방법 3: VS Code에서 실행

VS Code는 통합 개발 환경으로 코드 작성, 실행, 디버깅을 한 곳에서 할 수 있습니다.

실행 단계:

  1. VS Code에서 hello.py 파일 열기
  2. 실행 방법 3가지:
    • 방법 A: F5 키 누르기 (디버깅 모드)
    • 방법 B: 우측 상단 ▶️ 버튼 클릭 (일반 실행)
    • 방법 C: 우클릭 → “Run Python File in Terminal” 선택
  3. 첫 실행 시 “Python File” 선택
  4. 하단 터미널 패널에서 출력 확인

디버깅 모드 활용:

# debug_example.py
def calculate_sum(numbers):
    total = 0
    for num in numbers:  # ← 여기에 중단점 설정 (F9)
        total += num
    return total

numbers = [1, 2, 3, 4, 5]
result = calculate_sum(numbers)
print(f"합계: {result}")

디버깅 단계:

  1. 중단점 설정: 줄 번호 왼쪽 클릭 (빨간 점 표시)
  2. F5 키로 디버깅 시작
  3. 중단점에서 멈추면:
    • F10: 다음 줄로 이동 (Step Over)
    • F11: 함수 내부로 들어가기 (Step Into)
    • F5: 다음 중단점까지 계속 실행
  4. 좌측 패널에서 변수 값 실시간 확인

VS Code 터미널 활용:

# VS Code 내장 터미널 열기: Ctrl+` (백틱)
# 가상환경이 자동으로 활성화됩니다 (설정 시)

(venv) PS C:\project> python hello.py
# 코드 수정 후 바로 재실행 가능

실전 워크플로우:

  1. VS Code에서 코드 작성
  2. Ctrl+S로 저장 (자동 포맷팅 적용)
  3. F5 또는 터미널에서 실행
  4. 오류 발생 시 중단점 설정하여 디버깅
  5. 수정 후 재실행

설치·환경 확인에 자주 쓰는 명령

아래 명령은 “지금 쓰는 Python이 어디 것인지”와 패키지가 어디에 깔렸는지를 빠르게 확인할 때 씁니다. 가상환경을 쓸 때는 터미널 프롬프트에 (venv)가 보이는지와 함께 확인하면 실수가 줄어듭니다.

# Python 버전 확인
python --version

# pip 버전 확인
pip --version

# 설치 경로 확인
which python  # Mac/Linux
where python  # Windows

# 패키지 설치 위치 확인
python -m site

성능 팁

# pip 업그레이드 (최신 버전 사용)
pip install --upgrade pip

# 캐시 사용으로 설치 속도 향상
pip install --cache-dir ~/.cache/pip requests

코드 리뷰 팁

# ✅ 좋은 예: 가상환경 사용
# venv 폴더는 .gitignore에 추가

# ✅ 좋은 예: requirements.txt 관리
# pip freeze > requirements.txt

# ❌ 나쁜 예: 시스템 Python에 직접 설치
# sudo pip install ...  # 절대 하지 마세요!

자주 하는 실수

1. PATH 설정 안 함

# ❌ 에러
'python' is not recognized as an internal or external command

# ✅ 해결: PATH에 Python 경로 추가

2. python vs python3

# Mac/Linux에서는 python3 사용
python3 --version
pip3 install requests

# Windows에서는 python 사용
python --version
pip install requests

3. 가상환경 활성화 안 함

# ❌ 가상환경 활성화 안 하고 패키지 설치
pip install flask  # 시스템 Python에 설치됨!

# ✅ 가상환경 활성화 후 설치
source venv/bin/activate
pip install flask  # 가상환경에 설치됨

4. PowerShell 실행 정책

# ❌ 에러
venv\Scripts\Activate.ps1 cannot be loaded because running scripts is disabled

# ✅ 해결
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

트러블슈팅 가이드

문제 1: pip 설치 실패 - SSL 인증서 에러

증상:

pip install requests
# ERROR: Could not find a version that satisfies the requirement requests
# WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) 
# after connection broken by 'SSLError'

원인: 회사 방화벽, 프록시, 또는 인증서 문제로 PyPI 서버 접속 실패.

해결법:

# 방법 1: 신뢰할 수 있는 호스트 지정
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org requests

# 방법 2: pip 업그레이드 후 재시도
python -m pip install --upgrade pip
pip install requests

# 방법 3: 프록시 설정 (회사 네트워크)
pip install --proxy http://proxy.company.com:8080 requests

문제 2: 권한 에러 (Permission Denied)

증상:

pip install flask
# ERROR: Could not install packages due to an EnvironmentError: 
# [Errno 13] Permission denied

원인: 시스템 Python에 설치하려고 시도하여 관리자 권한 필요.

해결법:

# ❌ 나쁜 해결: sudo 사용 (시스템 Python 오염)
# sudo pip install flask  # 절대 하지 마세요!

# ✅ 좋은 해결 1: 가상환경 사용 (권장)
python -m venv venv
source venv/bin/activate  # Mac/Linux
# venv\Scripts\Activate.ps1  # Windows
pip install flask  # 가상환경에 설치 (권한 불필요)

# ✅ 좋은 해결 2: 사용자 디렉토리에 설치
pip install --user flask
# ~/.local/lib/python3.12/site-packages에 설치됨

문제 3: PowerShell 실행 정책 에러

증상:

venv\Scripts\Activate.ps1
# Activate.ps1 cannot be loaded because running scripts is disabled on this system.
# For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.

원인: Windows PowerShell의 기본 보안 정책이 스크립트 실행을 차단.

해결법:

# 방법 1: 현재 사용자에 대해 실행 정책 변경 (권장)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# 확인 메시지에 'Y' 입력

# 이후 가상환경 활성화
venv\Scripts\Activate.ps1

# 방법 2: 일회성 우회 (보안상 비권장)
PowerShell -ExecutionPolicy Bypass -File venv\Scripts\Activate.ps1

# 방법 3: CMD 사용
cmd
venv\Scripts\activate.bat

실행 정책 설명:

  • Restricted: 모든 스크립트 차단 (기본값)
  • RemoteSigned: 로컬 스크립트 허용, 다운로드한 스크립트는 서명 필요
  • Unrestricted: 모든 스크립트 허용 (보안 위험)

문제 4: python 명령을 찾을 수 없음

증상:

python --version
# 'python' is not recognized as an internal or external command

원인: Python이 PATH에 등록되지 않음.

해결법:

# 방법 1: Python 재설치 (Add to PATH 체크)
# python.org에서 설치 파일 다운로드 후 재설치

# 방법 2: PATH 수동 추가 (위의 "PATH 수동 추가" 섹션 참고)

# 방법 3: 전체 경로로 실행 (임시 방편)
C:\Users\YourName\AppData\Local\Programs\Python\Python312\python.exe --version

# 방법 4: py 런처 사용 (Windows 전용)
py --version
py -m pip install requests

py 런처 설명: Windows에는 py 명령이 기본 제공됩니다. Python이 PATH에 없어도 py 명령으로 실행할 수 있습니다.

문제 5: 가상환경 활성화 안 됨

증상: activate 명령 실행 후에도 프롬프트에 (venv) 표시가 없음.

확인 방법:

# 어느 Python을 사용 중인지 확인
where python  # Windows
which python  # Mac/Linux

# 시스템 Python 경로가 나오면 활성화 안 된 것
# C:\Users\YourName\AppData\Local\Programs\Python\Python312\python.exe

# 가상환경 Python 경로가 나와야 정상
# C:\project\venv\Scripts\python.exe

해결법:

# Windows PowerShell
.\venv\Scripts\Activate.ps1  # 상대 경로 명시

# Mac/Linux
source ./venv/bin/activate  # 상대 경로 명시

# 절대 경로 사용
source /full/path/to/venv/bin/activate

문제 6: 가상환경 삭제 및 재생성

가상환경이 손상되었거나 처음부터 다시 시작하고 싶을 때:

# 1. 가상환경 비활성화 (활성화 상태라면)
deactivate

# 2. 가상환경 폴더 삭제
# Mac/Linux
rm -rf venv

# Windows (PowerShell)
Remove-Item -Recurse -Force venv

# Windows (CMD)
rmdir /s /q venv

# 3. 새로 생성
python -m venv venv

# 4. 활성화 후 패키지 재설치
source venv/bin/activate  # Mac/Linux
# venv\Scripts\Activate.ps1  # Windows
pip install -r requirements.txt

문제 7: 패키지 버전 충돌

증상:

pip install package_a
# ERROR: package_a requires package_b>=2.0, but you have package_b 1.5

해결법:

# 방법 1: 충돌하는 패키지 업그레이드
pip install --upgrade package_b

# 방법 2: 특정 버전 조합 설치
pip install package_a==1.0.0 package_b==1.5.0

# 방법 3: 가상환경 새로 만들기 (깨끗한 상태에서 시작)
deactivate
rm -rf venv
python -m venv venv
source venv/bin/activate
pip install package_a

문제 8: pip가 오래된 버전

증상:

WARNING: You are using pip version 21.0.1; however, version 23.3.1 is available.

해결법:

# pip 자체를 업그레이드
python -m pip install --upgrade pip

# 또는 (가상환경 활성화 상태)
pip install --upgrade pip

실전 프로젝트 예제

예제 1: 간단한 계산기 프로그램

가상환경을 설정하고 첫 프로그램을 만들어봅시다.

# calculator.py - 간단한 계산기
def add(a, b):
    """두 숫자를 더합니다."""
    return a + b

def subtract(a, b):
    """두 숫자를 뺍니다."""
    return a - b

def multiply(a, b):
    """두 숫자를 곱합니다."""
    return a * b

def divide(a, b):
    """두 숫자를 나눕니다. 0으로 나누기 방지."""
    if b == 0:
        return "오류: 0으로 나눌 수 없습니다."
    return a / b

def main():
    """메인 함수 - 사용자 입력 받아 계산"""
    print("=" * 40)
    print("간단한 계산기 프로그램")
    print("=" * 40)
    
    # 사용자 입력
    num1 = float(input("첫 번째 숫자: "))
    operator = input("연산자 (+, -, *, /): ")
    num2 = float(input("두 번째 숫자: "))
    
    # 연산 수행
    if operator == "+":
        result = add(num1, num2)
    elif operator == "-":
        result = subtract(num1, num2)
    elif operator == "*":
        result = multiply(num1, num2)
    elif operator == "/":
        result = divide(num1, num2)
    else:
        result = "오류: 잘못된 연산자"
    
    print(f"\n결과: {num1} {operator} {num2} = {result}")

if __name__ == "__main__":
    main()

실행 및 테스트:

# 1. 가상환경 활성화
source venv/bin/activate

# 2. 프로그램 실행
python calculator.py

# 3. 입력 예시
# 첫 번째 숫자: 10
# 연산자 (+, -, *, /): *
# 두 번째 숫자: 5
# 결과: 10.0 * 5.0 = 50.0

예제 2: 외부 라이브러리 사용 (requests)

실제 프로젝트에서는 외부 라이브러리를 많이 사용합니다. HTTP 요청을 보내는 간단한 예제입니다.

# weather.py - 날씨 정보 가져오기
import requests

def get_weather(city):
    """
    OpenWeatherMap API로 날씨 정보 조회
    (실제 사용 시 API 키 필요)
    """
    # 예제용 더미 데이터
    weather_data = {
        "서울": {"temp": 15, "condition": "맑음"},
        "부산": {"temp": 18, "condition": "흐림"},
        "제주": {"temp": 20, "condition": "비"}
    }
    
    return weather_data.get(city, {"temp": 0, "condition": "정보 없음"})

def main():
    print("날씨 정보 조회 프로그램")
    city = input("도시 이름을 입력하세요 (서울/부산/제주): ")
    
    weather = get_weather(city)
    print(f"\n{city}의 날씨:")
    print(f"온도: {weather['temp']}°C")
    print(f"상태: {weather['condition']}")

if __name__ == "__main__":
    main()

패키지 설치 및 실행:

# 1. 가상환경 활성화
source venv/bin/activate

# 2. requests 라이브러리 설치
pip install requests

# 3. 프로그램 실행
python weather.py

# 4. 의존성 파일 생성 (팀 공유용)
pip freeze > requirements.txt

requirements.txt 내용 예시:

certifi==2023.7.22
charset-normalizer==3.3.0
idna==3.4
requests==2.31.0
urllib3==2.0.7

예제 3: 프로젝트 구조 예시

실전 Python 프로젝트의 표준 구조입니다.

my_project/
├── venv/                  # 가상환경 (Git에 올리지 않음)
├── src/                   # 소스 코드
│   ├── __init__.py
│   ├── main.py
│   └── utils.py
├── tests/                 # 테스트 코드
│   ├── __init__.py
│   └── test_utils.py
├── requirements.txt       # 의존성 목록
├── .gitignore             # Git 제외 파일 목록
├── README.md              # 프로젝트 설명
└── config.json            # 설정 파일

.gitignore 예시 (가상환경을 Git에 올리지 않기):

# Python
venv/
.venv/
__pycache__/
*.pyc
*.pyo
*.pyd
.Python

# IDE
.vscode/
.idea/

# 환경 설정
.env
config.local.json

프로젝트 초기 설정 스크립트:

# setup.sh (Mac/Linux) - 프로젝트 초기 설정 자동화
#!/bin/bash
echo "프로젝트 초기 설정 시작..."

# 가상환경 생성
python3 -m venv venv

# 가상환경 활성화
source venv/bin/activate

# pip 업그레이드
pip install --upgrade pip

# 의존성 설치
if [ -f requirements.txt ]; then
    pip install -r requirements.txt
    echo "의존성 설치 완료"
else
    echo "requirements.txt 없음"
fi

echo "설정 완료! 'source venv/bin/activate'로 활성화하세요."
# setup.ps1 (Windows) - 프로젝트 초기 설정 자동화
Write-Host "프로젝트 초기 설정 시작..." -ForegroundColor Green

# 가상환경 생성
python -m venv venv

# 가상환경 활성화
.\venv\Scripts\Activate.ps1

# pip 업그레이드
pip install --upgrade pip

# 의존성 설치
if (Test-Path requirements.txt) {
    pip install -r requirements.txt
    Write-Host "의존성 설치 완료" -ForegroundColor Green
} else {
    Write-Host "requirements.txt 없음" -ForegroundColor Yellow
}

Write-Host "설정 완료!" -ForegroundColor Green

사용법:

# Mac/Linux
chmod +x setup.sh
./setup.sh

# Windows
.\setup.ps1

정리

핵심 요약

  1. Python 설치: python.org, Mac은 Homebrew·pyenv로도 관리 가능
  2. 버전: 새 코드는 Python 3만; 최소 3.9+ 권장(타입 힌트·생태계)
  3. pip / requirements.txt / Poetry: pip가 기본, 팀 표준화에는 Poetry·pyproject.toml 검토
  4. 가상환경: 표준 venv, 필요 시 virtualenv·conda
  5. IDE: VS Code(Python 확장) 또는 PyCharm—인터프리터는 항상 가상환경으로
  6. 폴더: src/, tests/, .gitignore로 협업·CI에 맞게 정리
  7. 실행: python 파일명.py 또는 VS Code/PyCharm에서 디버그 실행

환경 설정 체크리스트

초기 설정 시:

  • Python 3.12 이상 설치 완료
  • python --version 명령 정상 작동
  • pip --version 명령 정상 작동
  • VS Code 설치 및 Python 확장 설치
  • 첫 프로그램 실행 성공

프로젝트 시작 시:

  • 프로젝트 폴더 생성
  • 가상환경 생성 (python -m venv venv)
  • 가상환경 활성화 확인 ((venv) 표시)
  • pip 업그레이드 (pip install --upgrade pip)
  • 필요한 패키지 설치
  • requirements.txt 생성
  • .gitignore에 venv/ 추가

일상 개발 시:

  • 작업 시작 시 가상환경 활성화
  • 새 패키지 설치 후 requirements.txt 갱신
  • 작업 종료 시 가상환경 비활성화

다음 단계

환경 설정을 완료했다면, 이제 Python 문법을 배울 차례입니다.

  • Python 기본 문법 | 변수, 연산자, 조건문, 반복문
  • Python 자료형 | 리스트, 딕셔너리, 튜플, 세트
  • Python 함수 | 매개변수, 반환값, 람다, 데코레이터

고급 주제

Anaconda vs Python 공식 배포판

Anaconda는 데이터 과학을 위한 Python 배포판으로, 수백 개의 패키지가 사전 설치되어 있습니다.

비교표:

특징Python 공식 배포판Anaconda
설치 크기~30MB~3GB
사전 설치 패키지없음 (필요할 때 설치)NumPy, Pandas, Matplotlib 등 250+
패키지 관리자pipconda + pip
가상환경venvconda env
적합한 용도웹 개발, 일반 프로그래밍데이터 분석, 머신러닝
학습 곡선낮음중간

선택 가이드:

  • 웹 개발 (Django, Flask): Python 공식 배포판 + pip
  • 데이터 분석 (Pandas, Jupyter): Anaconda
  • 머신러닝 (TensorFlow, PyTorch): Anaconda 또는 Python + pip
  • 초보자: Python 공식 배포판 (간단함)

pyenv로 여러 Python 버전 관리

프로젝트마다 다른 Python 버전이 필요할 때 pyenv를 사용합니다.

설치 (Mac/Linux):

# Mac
brew install pyenv

# Linux
curl https://pyenv.run | bash

# 설치 확인
pyenv --version

사용법:

# 설치 가능한 Python 버전 목록
pyenv install --list

# Python 3.11.0 설치
pyenv install 3.11.0

# Python 3.12.0 설치
pyenv install 3.12.0

# 전역 버전 설정
pyenv global 3.12.0

# 프로젝트별 버전 설정
cd my_project
pyenv local 3.11.0
# .python-version 파일 생성됨

# 현재 버전 확인
pyenv version

Docker로 Python 환경 격리

팀 전체가 완전히 동일한 환경을 사용하려면 Docker를 활용합니다.

Dockerfile 예시:

# Dockerfile
FROM python:3.12-slim

# 작업 디렉토리 설정
WORKDIR /app

# 의존성 파일 복사 및 설치
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 소스 코드 복사
COPY . .

# 애플리케이션 실행
CMD ["python", "main.py"]

사용법:

# Docker 이미지 빌드
docker build -t my-python-app .

# 컨테이너 실행
docker run my-python-app

# 개발 모드 (로컬 코드 마운트)
docker run -v $(pwd):/app my-python-app

CI/CD 환경에서의 Python 설정

GitHub Actions에서 Python 프로젝트를 자동 테스트하는 예제입니다.

.github/workflows/test.yml:

name: Python Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.10, 3.11, 3.12]
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
    
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
        pip install pytest
    
    - name: Run tests
      run: pytest

설명: 이 워크플로우는 코드를 push할 때마다 Python 3.10, 3.11, 3.12 세 버전에서 자동으로 테스트를 실행합니다.

같이 보면 좋은 글

공식 문서

관련 도구

내부 링크

  • Python 기본 문법 | 변수, 연산자, 조건문, 반복문
  • Python 자료형 | 리스트, 딕셔너리, 튜플, 세트
  • Python 모듈과 패키지 | import, init.py, 패키지 구조

이 글에서 다루는 키워드 (관련 검색어)

Python 설치, Python 환경 설정, pip 사용법, 가상환경 venv, conda, Poetry, VS Code Python, PyCharm, requirements.txt, pyenv, src 레이아웃, Python 개발 환경, Python 초보자, Python 시작하기, Python PATH 설정, 가상환경 활성화, pip install 등으로 검색하시면 이 글이 도움이 됩니다.

마치며

Python 환경 설정은 한 번만 제대로 하면 이후 개발이 매우 편해집니다. 특히 가상환경은 처음에는 번거로워 보이지만, 프로젝트가 많아질수록 그 가치를 실감하게 됩니다.

핵심 원칙 3가지:

  1. 가상환경 필수: 프로젝트마다 독립적인 환경 (의존성 충돌 방지)
  2. requirements.txt 관리: 의존성을 파일로 관리 (팀 협업, 배포 시 필수)
  3. 시스템 Python 건드리지 않기: 항상 가상환경 사용 (안전성)

가상환경을 켰다 껐다 하는 과정은 처음에는 번거로울 수 있습니다. 다만 프로젝트마다 다른 버전의 Django·NumPy 등을 동시에 써야 할 때는, 가상환경이 없으면 패키지가 덮어씌워지며 깨지기 쉽습니다. 처음부터 프로젝트 폴더마다 venv를 두는 습관을 들이면 이후에 시간을 아낄 수 있습니다.

환경 설정이 끝났다면 Python 기본 문법에서 변수·조건문·반복문을 이어서 읽어 보세요. 예제는 직접 타이핑해 보시면 단순히 읽는 것보다 훨씬 빨리 익숙해집니다.

관련 글

  • Python 기본 문법 | 변수, 연산자, 조건문, 반복문 완벽 가이드
  • Python 자료형 | 리스트, 딕셔너리, 튜플, 세트 완벽 가이드
  • Python 모듈과 패키지 | import, pip, 가상환경 완벽 정리
  • TypeScript 시작하기 | 설치, 설정, 기본 문법
  • 배열과 리스트 | 코딩 테스트 필수 자료구조 완벽 정리