[파이썬] Ubuntu / Linux Python 가상환경(venv) 설치 및 프로젝트 환경 구성

Python 프로젝트를 진행할 때 가상환경(Virtual Environment)을 사용하면 프로젝트별로 독립적인 패키지 관리가 가능합니다.

이번에는 Ubuntu 환경에서 Python 가상환경을 생성하고, 필요한 라이브러리를 설치하는 과정을 정리해보겠습니다.

 

** 들어가기 앞서 : 독립적인 패키지 관리 하는 이유 

왜 Python 가상환경(Virtual Environment)이 필요할까?

Ubuntu와 같은 Linux 운영체제는 내부적으로 System Python이라는 기본 Python 환경을 사용합니다.

이 System Python은 운영체제의 여러 기능과 패키지 관리 도구가 의존하고 있기 때문에 임의로 수정하거나 패키지를 마구 설치하면 시스템 전체에 영향을 줄 수 있습니다.

System Python 사용 예시
- apt 패키지 관리자
- Ubuntu 시스템 스크립트
- 운영체제 내부 관리 도구

만약 프로젝트 개발 중 필요한 라이브러리를 System Python에 직접 설치하게 되면 버전 충돌이 발생할 수 있습니다.

예를 들어,

• 프로젝트 A는 PySide6 6.11 버전 필요
• 프로젝트 B는 PySide6 최신 버전 필요
• 운영체제는 특정 Python 버전을 기준으로 동작

이런 상황에서 하나의 Python 환경만 사용하면 패키지 버전이 서로 충돌하면서 프로젝트 실행 오류가 발생할 수 있습니다.

그래서 사용하는 것이 가상환경(Virtual Environment)입니다.

가상환경은 프로젝트마다 독립적인 Python 공간을 만들어주는 기능입니다.

System Python (운영체제용)
 └── 건드리지 않음

Project_A
 └── .venv
      └── PySide6 6.11

Project_B
 └── .venv
      └── Flask 최신버전

즉, 프로젝트마다 필요한 라이브러리를 따로 설치할 수 있어서 서로 영향을 주지 않습니다.

또한 개발 환경을 팀원과 동일하게 맞추기 쉬워지고, requirements.txt 파일을 통해 같은 환경을 빠르게 재현할 수 있다는 장점도 있습니다.

정리하면 가상환경을 사용하는 이유는 다음과 같습니다.

• 운영체제 기본 Python 보호
• 프로젝트별 패키지 충돌 방지
• Python 버전 독립 관리
• 팀 프로젝트 환경 통일
• 배포 및 재설치 편의성 향상

---

1. 프로젝트 폴더 생성

mkdir -p ~/Dev/Project_New

설명
mkdir : 폴더 생성 명령어
-p : 상위 폴더가 없어도 함께 생성

2. 프로젝트 폴더로 이동

cd ~/Dev/Project_New

현재 위치 확인:

pwd

예상 출력:

/home/joy/Dev/Project_New

3. Python 가상환경 생성

python3.13 -m venv .venv

설명
python3.13 : 사용할 Python 버전 지정
-m venv : 가상환경 생성 모듈 실행
.venv : 가상환경 폴더명

생성 후 프로젝트 내부에 숨김 폴더 형태로 저장됩니다.

Project_New/
 └── .venv/

4. 가상환경 활성화

source .venv/bin/activate

성공 시 터미널 앞에 가상환경 이름이 표시됩니다.

(.venv) joy@joy-DT281:~/Dev/Project_New$

5. Python 버전 확인

python --version

출력 예시:

Python 3.13.13

6. 필요한 라이브러리 설치

이번 프로젝트에서 설치한 패키지는 다음과 같습니다.

• PySide6
• mysql-connector-python

python -m pip install PySide6 mysql-connector-python

설치 완료 후 아래와 같은 메시지가 출력되면 정상 설치입니다.

Successfully installed

7. requirements.txt 생성

현재 설치된 패키지 목록을 저장합니다.

python -m pip freeze > requirements.txt

requirements.txt 파일을 통해 다른 환경에서도 동일한 패키지 구성을 재현할 수 있습니다.

8. requirements.txt 기반 패키지 설치

python -m pip install -r requirements.txt

-r 옵션은 requirements 파일을 읽어 설치하겠다는 의미입니다.

9. 프로젝트 기본 파일 생성

touch main.py
touch database.py
touch window.py

생성되는 파일:

main.py
database.py
window.py

10. 설치된 패키지 확인

ls .venv/lib/python3.13/site-packages

예시 출력:

PySide6
mysql
pip
shiboken6

site-packages는 설치된 Python 라이브러리가 저장되는 위치입니다.

최종 프로젝트 구조

Project_New/
 ├── .venv/
 ├── main.py
 ├── database.py
 ├── window.py
 └── requirements.txt

정리

• 프로젝트 폴더 생성
• Python 가상환경 생성
• 가상환경 활성화
• Python 버전 확인
• 라이브러리 설치
• requirements.txt 생성
• 패키지 재설치 테스트
• 기본 프로젝트 파일 구성

이렇게 구성하면 프로젝트마다 독립적인 Python 개발 환경을 만들 수 있어 패키지 충돌 없이 안정적으로 개발할 수 있습니다.