Search

[참고사항] 파이션 가상환경 설정 방법

생성일
2026/10/06 03:45
태그

🐍 Python 기초 실습 01 — 가상환경(venv) 만들기

교육 목표: Python 프로젝트마다 독립적인 개발환경을 생성하고, 라이브러리를 설치한 후 Python 프로그램과 Streamlit 웹 애플리케이션을 실행할 수 있다.
항목
교육 내용
교육 대상
Python을 처음 배우는 입문자
실습 환경
Windows 11, Python 3.x, VS Code
실습 시간
약 90~120분
실습 방식
개념 20% + 실습 80%
프로젝트 경로
C:\python-venv-lab
가상환경 이름
.venv
실습 결과물
Python 프로그램 및 Streamlit 웹앱

📘 01. Python 가상환경이란?

1.1 가상환경의 개념

Python을 컴퓨터에 설치하면 기본 Python 실행 환경을 사용할 수 있습니다.
그런데 Python으로 여러 프로젝트를 개발하다 보면 프로젝트마다 필요한 라이브러리와 버전이 달라질 수 있습니다.
예를 들어 다음과 같은 프로젝트를 개발한다고 가정하겠습니다.
프로젝트
사용 목적
주요 라이브러리
프로젝트 A
AI 챗봇 개발
streamlit, boto3
프로젝트 B
웹 API 서버 개발
fastapi, uvicorn
프로젝트 C
데이터 분석
pandas, numpy
이러한 프로젝트에서 모든 라이브러리를 하나의 Python 환경에 설치하면 버전 충돌이나 의존성 문제가 발생할 수 있습니다.
Python 가상환경(venv)은 각 프로젝트가 독립적인 라이브러리 설치 공간을 갖도록 만들어 주는 기능입니다.

1.2 가상환경 구조

각 프로젝트는 별도의 라이브러리 설치 공간을 사용합니다.

1.3 가상환경을 사용하는 이유

가상환경을 사용하면 다음과 같은 장점이 있습니다.
•
패키지 충돌 방지: 프로젝트마다 다른 버전의 라이브러리를 사용할 수 있습니다.
•
프로젝트 독립성 유지: 한 프로젝트에서 패키지를 설치하거나 삭제해도 다른 가상환경에 영향을 주지 않습니다.
•
개발환경 재현: requirements.txt를 통해 필요한 패키지를 다시 설치할 수 있습니다.
•
유지보수 편리: 프로젝트별로 필요한 라이브러리만 관리할 수 있습니다.
💡 강사 설명 포인트
가상환경은 컴퓨터를 여러 대 만드는 것이 아닙니다. 하나의 컴퓨터에서 프로젝트별로 독립된 Python 실행 환경과 패키지 저장 공간을 사용하는 방식입니다.

💻 02. Python 실습 환경 준비하기

2.1 필요한 프로그램

실습을 시작하기 전에 다음 프로그램이 설치되어 있어야 합니다.
프로그램
설명
설치 확인
Python 3.x
Python 코드 실행
python --version
VS Code
코드 작성 도구
프로그램 실행
pip
Python 패키지 관리
python -m pip --version
venv
가상환경 생성
python -m venv --help
Python 다운로드: Python 공식 사이트

2.2 VS Code 실행하기

1.
VS Code를 실행합니다.
2.
상단 메뉴에서 **파일(File) → 폴더 열기(Open Folder)**를 선택합니다.
3.
작업할 폴더를 선택합니다.
4.
상단 메뉴에서 **터미널(Terminal) → 새 터미널(New Terminal)**을 선택합니다.
VS Code 터미널은 코드 작성 화면 아래쪽에 나타납니다.

2.3 Python 설치 여부 확인

터미널에 다음 명령어를 입력합니다.
python --version
Plain Text
복사
정상 실행 결과 예시:
Python 3.13.7
Plain Text
복사
Windows에서 여러 Python 버전이 설치되어 있다면 다음 명령어로 확인할 수 있습니다.
py -0p
Plain Text
복사
실행 결과 예시:
-V:3.13 C:\Python313\python.exe -V:3.11 C:\Python311\python.exe
Plain Text
복사
💡 python --version은 현재 실행되는 Python 버전을 보여 주고, py -0p는 Windows Python Launcher가 인식하는 Python 설치 목록을 보여 줍니다.

📁 03. Python 프로젝트 폴더 생성하기

3.1 프로젝트 폴더란?

프로젝트 폴더는 Python 소스코드, 가상환경, 설정 파일, 라이브러리 목록 등을 보관하는 작업 공간입니다.
이번 실습에서는 다음 경로를 사용합니다.
C:\python-venv-lab

3.2 CMD에서 폴더 생성하기

VS Code 터미널을 CMD(Command Prompt)로 설정한 후 다음 명령어를 실행합니다.
mkdir C:\python-venv-lab
Plain Text
복사
프로젝트 폴더로 이동합니다.
cd /d C:\python-venv-lab
Plain Text
복사
명령어 설명:
명령어
의미
mkdir
새로운 폴더 생성
cd
폴더 이동
/d
드라이브까지 함께 변경
C:\python-venv-lab
실습 프로젝트 경로
정상 실행 시 터미널에 다음과 같이 표시됩니다.
C:\python-venv-lab>
Plain Text
복사

3.3 VS Code에서 프로젝트 폴더 열기

VS Code에서 파일 → 폴더 열기를 선택한 후 C:\python-venv-lab을 엽니다.
이제 이 폴더에서 Python 코드를 작성합니다.

🛠️ 04. Python 가상환경 생성하기

4.1 가상환경 생성 명령어

프로젝트 폴더에서 다음 명령어를 실행합니다.
python -m venv .venv
Plain Text
복사
명령어의 각 항목을 살펴보겠습니다.
명령어
의미
python
Python 실행
-m
Python 모듈을 실행하는 옵션
venv
가상환경 생성 모듈
.venv
생성할 가상환경 폴더 이름
python -m venv .venv는 현재 폴더에 .venv라는 가상환경을 생성하라는 의미입니다.

4.2 가상환경 생성 결과

명령어가 정상 실행되면 VS Code 탐색기에 .venv 폴더가 생성됩니다.
C:\python-venv-lab │ └── .venv ├── Include ├── Lib │ └── site-packages ├── Scripts │ ├── python.exe │ ├── pip.exe │ ├── activate.bat │ └── Activate.ps1 └── pyvenv.cfg
Plain Text
복사
주요 폴더의 역할:
폴더 및 파일
역할
Scripts
Python 실행 파일 및 활성화 스크립트
Lib
Python 라이브러리 관련 폴더
site-packages
pip으로 설치한 라이브러리 저장
pyvenv.cfg
가상환경 설정 정보

4.3 .venv와 venv의 차이

두 이름 모두 사용할 수 있습니다.
python -m venv venv
Plain Text
복사
또는
python -m venv .venv
Plain Text
복사
기능상의 차이는 없습니다. 단지 생성되는 폴더 이름이 다릅니다.
이번 실습에서는 VS Code 프로젝트에서 많이 사용하는 .venv를 사용합니다.
⚠️ 주의
가상환경은 프로젝트마다 한 번 생성하면 됩니다. 프로젝트를 실행할 때마다 새로 생성할 필요는 없습니다.

▶️ 05. 가상환경 활성화하기

5.1 가상환경 활성화란?

가상환경을 생성했다고 해서 자동으로 활성화되는 것은 아닙니다.
가상환경을 활성화하면 현재 터미널에서 해당 가상환경의 Python과 pip을 우선 사용하게 됩니다.

5.2 Windows CMD에서 활성화하기

.venv\Scripts\activate
Plain Text
복사
정상 실행 결과:
(.venv) C:\python-venv-lab>
Plain Text
복사
터미널 앞에 (.venv)가 표시되면 활성화된 상태입니다.

5.3 Windows PowerShell에서 활성화하기

.\.venv\Scripts\Activate.ps1
Plain Text
복사
PowerShell에서 스크립트 실행 정책 오류가 발생한다면 현재 세션에 한해 다음 명령어를 사용할 수 있습니다.
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
Plain Text
복사
그다음 활성화 명령어를 다시 실행합니다.
가상환경 생성은 CMD와 PowerShell 모두 가능하지만, PowerShell에서는 활성화 스크립트 실행 정책으로 인해 오류가 발생할 수 있습니다.

5.4 macOS 및 Linux에서 활성화하기

source .venv/bin/activate
Plain Text
복사

5.5 활성화 여부 확인하기

다음 명령어를 실행합니다.
python -c "import sys; print(sys.executable)"
Plain Text
복사
정상 실행 결과 예시:
C:\python-venv-lab\.venv\Scripts\python.exe
Plain Text
복사
이 경로가 출력되면 가상환경의 Python을 사용하고 있다는 의미입니다.

📦 06. pip을 이용한 라이브러리 설치

6.1 pip이란?

pip은 Python 패키지 설치 및 관리 도구입니다.
Python에는 기본 기능이 포함되어 있지만, 웹 개발이나 AI 개발을 위해서는 추가 라이브러리가 필요한 경우가 많습니다.
예를 들어 다음과 같습니다.
라이브러리
용도
streamlit
Python 웹 애플리케이션 개발
boto3
AWS 서비스 연동
fastapi
웹 API 서버 개발
pandas
데이터 분석
python-dotenv
환경변수 파일 관리

6.2 pip 업그레이드하기

가상환경이 활성화된 상태에서 다음 명령어를 실행합니다.
python -m pip install --upgrade pip
Plain Text
복사

6.3 라이브러리 설치하기

이번 실습에서는 Streamlit을 설치합니다.
python -m pip install streamlit
Plain Text
복사
AWS 연동과 환경변수 관리 라이브러리도 설치합니다.
python -m pip install boto3 python-dotenv
Plain Text
복사
여러 라이브러리를 한 번에 설치할 수도 있습니다.
python -m pip install streamlit boto3 python-dotenv
Plain Text
복사

6.4 설치된 라이브러리 확인하기

pip list
Plain Text
복사
설치된 패키지 이름과 버전이 출력됩니다.
특정 라이브러리의 설치 정보를 확인하려면 다음 명령어를 실행합니다.
pip show streamlit
Plain Text
복사

🧪 07. 첫 번째 Python 프로그램 실행하기

7.1 Python 파일 생성

VS Code 탐색기에서 새 파일을 생성합니다.
파일 이름:
app.py
다음 코드를 입력합니다.
# ================================================== # Python 가상환경 첫 번째 실습 # ================================================== print("안녕하세요!") print("Python 가상환경 실습입니다.") print("Python 프로그램 실행에 성공했습니다.").2 프로그램 실행
Plain Text
복사
python app.py
Plain Text
복사
실행 결과:
안녕하세요! Python 가상환경 실습입니다. Python 프로그램 실행에 성공했습니다.
Plain Text
복사

7.3 코드 설명

코드
설명
#
주석 작성
print()
화면에 문자 또는 값 출력
"안녕하세요!"
문자열 데이터
python app.py
Python 파일 실행
💡 실습 확인
위 세 문장이 터미널에 정상 출력되면 Python 가상환경에서 프로그램을 실행하는 데 성공한 것입니다.

🌐 08. Streamlit 웹 애플리케이션 만들기

이번 실습에서는 Python으로 간단한 웹페이지를 만들어 보겠습니다.

8.1 Streamlit이란?

Streamlit은 Python 코드만으로 웹 애플리케이션을 만들 수 있도록 도와주는 라이브러리입니다.
HTML, CSS, JavaScript를 직접 작성하지 않고도 간단한 웹 화면을 만들 수 있습니다.

8.2 Streamlit 설치

python -m pip install streamlit
Plain Text
복사

8.3 Streamlit 프로그램 작성

app.py 파일의 기존 코드를 다음 코드로 변경합니다.
# ================================================== # Streamlit 웹 애플리케이션 실습 # ================================================== import streamlit as st # 웹페이지 제목 st.title("나의 첫 번째 Python 웹앱") # 안내 문구 st.write("Python 가상환경 실습에 성공했습니다!") # 사용자 이름 입력 name = st.text_input("이름을 입력하세요") # 버튼 클릭 처리 if st.button("인사하기"): if name: st.success(f"{name}님, 반갑습니다!") else: st.warning("이름을 입력해주세요.")
Plain Text
복사

8.4 Streamlit 실행

터미널에서 다음 명령어를 실행합니다.
streamlit run app.py
Plain Text
복사
정상 실행되면 다음과 비슷한 메시지가 출력됩니다.
You can now view your Streamlit app in your browser. Local URL: http://localhost:8501 Network URL: http://192.168.x.x:8501
Plain Text
복사
웹브라우저에서 http://localhost:8501로 접속합니다.

8.5 실행 화면 예시

Streamlit 웹앱 화면 예시

나의 첫 번째 Python 웹앱

Python 가상환경 실습에 성공했습니다!
이름을 입력하세요
인사하기
실제 Streamlit 웹앱의 동작을 이해하기 위한 체험 화면입니다.

8.6 Streamlit 종료하기

실행 중인 터미널에서 다음 키를 누릅니다.
Ctrl + C
그러면 Streamlit 서버가 종료됩니다.

📄 09. requirements.txt 파일 활용하기

9.1 requirements.txt란?

Python 프로젝트에서 사용하는 라이브러리와 버전 정보를 저장하는 파일입니다.
다른 컴퓨터에서 동일한 개발환경을 구성하거나 팀원과 프로젝트를 공유할 때 사용합니다.

9.2 라이브러리 목록 저장

python -m pip freeze > requirements.txt
Plain Text
복사
생성된 파일에는 다음과 같은 내용이 저장됩니다.
streamlit==설치된버전 boto3==설치된버전 python-dotenv==설치된버전 ...
Plain Text
복사
실제 파일에는 버전 번호와 의존성 패키지가 함께 기록됩니다.

9.3 라이브러리 재설치

새로운 가상환경을 생성한 후 다음 명령어를 실행합니다.
python -m pip install -r requirements.txt
Plain Text
복사
pip은 파일에 기록된 라이브러리를 설치합니다.
💡 requirements.txt는 Python 인터프리터 자체를 설치하는 파일이 아닙니다. 프로젝트에서 사용할 Python 버전은 별도로 맞추어야 합니다.

🔐 10. .env 파일과 환경변수 이해하기

10.1 .env 파일이란?

.env는 프로그램에서 사용할 설정값을 관리하는 파일입니다.
예를 들어 AWS 리전이나 모델 ID 등을 저장할 수 있습니다.
AWS_REGION=ap-northeast-2 APP_NAME=PythonVenvLab
Plain Text
복사

10.2 python-dotenv 설치

python -m pip install python-dotenv
Plain Text
복사

10.3 Python에서 .env 파일 읽기

import os from dotenv import load_dotenv # .env 파일 로드 load_dotenv() # 환경변수 가져오기 region = os.getenv("AWS_REGION") app_name = os.getenv("APP_NAME") print("AWS 리전:", region) print("프로젝트 이름:", app_name)
Plain Text
복사
실행 결과:
AWS 리전: ap-northeast-2 프로젝트 이름: PythonVenvLab
Plain Text
복사
중요: .venv와 .env는 서로 다른 개념입니다.
구분
역할
.venv
Python 가상환경 폴더
.env
프로그램 설정 및 환경변수 파일
가상환경을 활성화하는 것만으로 .env 파일이 자동 로드되지는 않습니다.
또한 .env에 비밀번호나 API 키를 저장하는 경우 GitHub 등 공개 저장소에 업로드하지 않도록 주의해야 합니다.

🗂️ 11. 최종 프로젝트 폴더 구조

모든 실습을 완료하면 프로젝트는 다음과 같이 구성됩니다.
C:\python-venv-lab │ ├── .venv/ │ ├── Include/ │ ├── Lib/ │ ├── Scripts/ │ └── pyvenv.cfg │ ├── app.py │ ├── .env │ ├── requirements.txt │ └── .gitignore
Plain Text
복사
각 파일의 역할은 다음과 같습니다.
파일 및 폴더
설명
.venv/
Python 가상환경
app.py
Python 프로그램
.env
환경변수 설정
requirements.txt
라이브러리 목록
.gitignore
Git 업로드 제외 설정
.gitignore 파일에는 다음 내용을 작성할 수 있습니다.
.venv/ .env __pycache__/ *.pyc
Plain Text
복사

🧯 12. 자주 발생하는 오류와 해결 방법

오류 1. Python 명령어를 찾을 수 없는 경우

'python' is not recognized as an internal or external command
Plain Text
복사
원인: Python이 설치되지 않았거나 PATH 환경변수가 올바르게 설정되지 않았을 수 있습니다.
해결 방법: Python 설치 상태를 확인하고 다음 명령어를 실행합니다.
py --version
Plain Text
복사

오류 2. 가상환경 활성화가 되지 않는 경우

running scripts is disabled on this system
Plain Text
복사
원인: PowerShell의 스크립트 실행 정책에 의해 활성화가 차단된 경우입니다.
해결 방법: CMD에서 다음 명령어를 사용합니다.
.venv\Scripts\activate
Plain Text
복사

오류 3. 라이브러리를 찾을 수 없는 경우

ModuleNotFoundError: No module named 'streamlit'
Plain Text
복사
원인: 현재 사용하는 Python 환경에 해당 라이브러리가 설치되지 않았을 수 있습니다.
해결 방법:
python -m pip install streamlit
Plain Text
복사

오류 4. 가상환경의 Python이 아닌 경우

다음 명령어로 Python 실행 경로를 확인합니다.
python -c "import sys; print(sys.executable)"
Plain Text
복사
가상환경 경로가 아니라면 VS Code에서 Ctrl + Shift + P를 누른 후 Python: Select Interpreter를 선택하여 .venv의 Python을 지정합니다.

📌 13. 핵심 명령어 한눈에 보기

작업
명령어
Python 버전 확인
python --version
프로젝트 폴더 생성
mkdir C:\python-venv-lab
프로젝트 폴더 이동
cd /d C:\python-venv-lab
가상환경 생성
python -m venv .venv
CMD 가상환경 활성화
.venv\Scripts\activate
pip 업그레이드
python -m pip install --upgrade pip
라이브러리 설치
python -m pip install streamlit
설치 목록 확인
pip list
Python 실행
python app.py
Streamlit 실행
streamlit run app.py
패키지 목록 저장
pip freeze > requirements.txt
패키지 일괄 설치
pip install -r requirements.txt
가상환경 종료
deactivate
최종 학습 성과: 수강생이 스스로 Python 가상환경을 만들고, 라이브러리를 설치하고, 웹 애플리케이션을 실행할 수 있습니다.