파이썬(Python) 공부 11편 — 모듈·패키지·pip 완전 정복 | import·표준 라이브러리·pip·가상환경·__name__까지

11 / 15 Python 공부 시리즈 — 모듈·패키지·pip

← 10편: 클래스와 객체지향 기초 보러 가기

Python 공부 시리즈 · 11편 | import · 표준 라이브러리 · pip · 가상환경

파이썬(Python) 공부 11편
모듈·패키지·pip 완전 정복

파이썬의 진짜 강점은 방대한 생태계에 있습니다. 내가 필요한 기능 대부분은 이미 누군가 만들어 놨고, 단 한 줄의 import로 가져다 쓸 수 있습니다. 모듈·패키지의 개념부터 표준 라이브러리 활용, pip로 외부 패키지 관리, 프로젝트마다 환경을 분리하는 가상환경까지 한 번에 정리합니다.

모듈 / 패키지 import 방법 4가지 표준 라이브러리 pip 패키지 관리 가상환경 (venv) __name__ == "__main__"

---

📁 모듈(Module)과 패키지(Package) — 개념 정리

파이썬 코드를 쓰다 보면 같은 함수를 여러 파일에서 쓰고 싶어지는 순간이 옵니다. 이때 모듈이 등장합니다. 모듈은 간단히 말해. py 파일 하나입니다. 함수·클래스·변수를 담아두고, 다른 파일에서 import 해 재사용할 수 있습니다.

Module 모듈 — .py 파일 하나

함수·클래스·변수를 담은 단일 파이썬 파일.
예: math.py, os.py, 내가 만든 utils.py

Package 패키지 — 모듈의 묶음(폴더)

여러 모듈을 폴더로 묶은 것.
__init__.py가 있는 폴더가 패키지.
예: numpy, requests, django

▲ 파이썬의 강점은 풍부한 표준 라이브러리와 PyPI에 등록된 50만 개 이상의 외부 패키지에 있다. import 한 줄이면 수천 줄의 작업을 대신할 수 있다. (출처: Unsplash / 참고 이미지)

---

🔄 import 방법 4가지 — 상황에 맞게 골라 쓰기

 

import_ways.py

# ① import 모듈명 — 모듈 전체 가져오기
import math
print(math.pi)           # 3.141592…  (모듈명.속성 으로 접근)
print(math.sqrt(16))    # 4.0

# ② from 모듈 import 이름 — 특정 것만 가져오기
from math import pi, sqrt
print(pi)                # 3.141592…  (모듈명 없이 바로 사용)
print(sqrt(25))          # 5.0

# ③ import 모듈 as 별명 — 긴 이름에 별명 붙이기
import numpy as np         # 관례적 별명 (numpy → np)
import pandas as pd        # 관례적 별명 (pandas → pd)
import matplotlib.pyplot as plt  # 서브 모듈에 별명

# ④ from 모듈 import * — 모든 것 가져오기 (권장하지 않음)
from math import *
print(ceil(3.2))           # 4  (어디서 왔는지 불명확 → 이름 충돌 위험)

⚠️ from 모듈 import * 는 가능하면 피할 것

• 어떤 이름이 어느 모듈에서 왔는지 추적하기 어려워짐
• 기존 변수 이름과 충돌해 예상치 못한 버그 발생 가능
• 코드 리뷰·유지보수 시 가독성 저하
• Jupyter Notebook 탐색 목적 등 특수한 경우를 제외하면 지양

---

🔨 직접 모듈 만들기 —. py 파일이 곧 모듈

 

mymath.py — 내가 만든 모듈

# mymath.py
PI = 3.14159

def add(a, b):
    return a + b

def circle_area(r):
    return PI * r ** 2

class Vector:
    def __init__(self, x, y):
        self.x, self.y = x, y

 

main.py — 내 모듈 가져다 쓰기

# main.py (mymath.py 와 같은 폴더에 위치)
import mymath

print(mymath.PI)                # 3.14159
print(mymath.add(3, 5))          # 8
print(mymath.circle_area(5))     # 78.53975

from mymath import Vector
v = Vector(1, 2)
print(v.x, v.y)                 # 1 2

---

⚡ __name__ == "__main__" — 꼭 알아야 할 패턴

파이썬 파일을 직접 실행할 때는 __name__이 "__main__"이 됩니다. 반면 다른 파일에서 import 할 때는 모듈 이름(파일명)이 됩니다. 이 차이를 이용하면 같은 파일을 모듈로도 쓰고, 직접 실행 스크립트로도 쓸 수 있습니다.

 

mymath.py — __name__ 활용

PI = 3.14159

def add(a, b):
    return a + b

# 이 블록은 직접 실행할 때만 동작, import 시에는 무시됨
if __name__ == "__main__":
    print("직접 실행됨")
    print(add(3, 5))         # 8  (직접 실행 시)

# python mymath.py  → "직접 실행됨", "8" 출력
# import mymath     → 아무것도 출력 안 됨

💡

실무 필수 패턴 모든 Python 스크립트에 if __name__ == "__main__": 을 쓰는 이유

테스트 코드·실행 예제·CLI 진입점을 이 블록 안에 넣으면 import 시 자동 실행되는 문제를 방지합니다.

• 직접 실행: python mymath.py → __name__ == "__main__" → if 블록 실행
• import할 때: import mymath → __name__ == "mymath" → if 블록 무시

이 패턴을 쓰지 않으면 누군가 내 모듈을 import했을 때 테스트 코드가 자동으로 실행되는 불상사가 생깁니다. 파이썬 파일 어디서나 볼 수 있는 관용 표현이니 익혀두세요.

---

📚 파이썬 표준 라이브러리 — 설치 없이 바로 쓰는 도구들

파이썬은 설치할 때부터 수백 개의 모듈이 함께 들어옵니다. 이것이 표준 라이브러리(Standard Library)입니다. pip 설치 없이 import 하나로 바로 쓸 수 있습니다.

모듈	용도	대표 사용 예
os	운영체제 인터페이스 (파일·폴더·환경변수)	os.getcwd(), os.listdir()
sys	파이썬 인터프리터 제어 (경로·버전·종료)	sys.argv, sys.exit()
pathlib	객체지향적 파일 경로 처리 (8편 참고)	Path("data") / "file.txt"
json	JSON 직렬화·역직렬화 (8편 참고)	json.dumps(), json.loads()
datetime	날짜·시간 처리	datetime.now(), timedelta
math	수학 함수·상수	math.sqrt(), math.pi
random	난수 생성	random.choice(), shuffle()
re	정규표현식	re.search(), re.findall()
collections	특수 컨테이너 (Counter, defaultdict 등)	Counter(words)
itertools	반복자 도구 (조합·순열·chain 등)	product(), combinations()
functools	함수 도구 (lru_cache, reduce 등)	@lru_cache, partial()
csv	CSV 파일 입출력 (8편 참고)	csv.reader(), DictWriter()
logging	로그 출력 (print 대신 쓰는 실무 도구)	logging.info(), warning()
subprocess	외부 프로세스·명령어 실행	subprocess.run(["ls"])
threading	멀티스레드 처리	Thread(target=func).start()
typing	타입 힌트 지원 (List, Dict, Optional 등)	def f(x: list[int]) -> str

 

stdlib_examples.py — 자주 쓰는 표준 라이브러리 예시

import os, sys, random
from datetime import datetime, timedelta
from collections import Counter, defaultdict

# os — 환경 정보
print(os.getcwd())           # 현재 작업 디렉토리
print(os.path.exists("data.txt"))  # 파일 존재 여부
os.makedirs("output", exist_ok=True)  # 폴더 생성

# datetime — 날짜·시간
now = datetime.now()
print(now.strftime("%Y-%m-%d %H:%M"))   # 2026-04-01 12:30
tomorrow = now + timedelta(days=1)
print(tomorrow.date())

# random — 난수
print(random.randint(1, 6))     # 주사위 굴리기
items = ["apple", "banana", "cherry"]
print(random.choice(items))      # 무작위 선택
random.shuffle(items)           # 섞기 (제자리)

# Counter — 요소 개수 세기
words = ["apple", "banana", "apple", "cherry", "apple"]
cnt = Counter(words)
print(cnt)                       # Counter({'apple': 3, 'banana': 1, 'cherry': 1})
print(cnt.most_common(2))        # [('apple', 3), ('banana', 1)]

# defaultdict — 키 없을 때 기본값 자동 생성
scores = defaultdict(list)
scores["Alice"].append(90)
scores["Alice"].append(85)
scores["Bob"].append(78)
print(dict(scores))              # {'Alice': [90, 85], 'Bob': [78]}

---

📦 pip — 외부 패키지 설치·관리

pip(Pip Installs Packages)는 파이썬 공식 패키지 관리 도구입니다. PyPI(Python Package Index)에 등록된 수십만 개의 패키지를 명령어 한 줄로 설치할 수 있습니다. 터미널(명령 프롬프트)에서 실행합니다.

명령어	설명	예시
pip install 패키지	패키지 최신 버전 설치	pip install requests
pip install 패키지==버전	특정 버전 설치	pip install numpy==1.26.0
pip install --upgrade 패키지	최신 버전으로 업그레이드	pip install --upgrade pip
pip uninstall 패키지	패키지 제거	pip uninstall requests
pip list	설치된 패키지 목록 보기	pip list
pip show 패키지	패키지 상세 정보	pip show numpy
pip freeze	설치 목록을 requirements.txt 형식으로	pip freeze > requirements.txt
pip install -r requirements.txt	requirements.txt에서 일괄 설치	팀 프로젝트 환경 복원
pip search 키워드	PyPI에서 패키지 검색	pip search http

📚

꼭 알아야 할 인기 외부 패키지 실무에서 자주 만나는 패키지 목록

• requests: HTTP 요청 — API 연동·웹 데이터 가져오기
• numpy: 수치 계산·행렬 연산 — 데이터 과학의 기반
• pandas: 데이터프레임 — 테이블 데이터 분석 필수
• matplotlib / seaborn: 데이터 시각화
• Flask / FastAPI: 웹 서버·REST API 개발
• SQLAlchemy: 데이터베이스 ORM
• Pillow: 이미지 처리 (PIL 후속)
• pytest: 테스트 프레임워크
• python-dotenv: .env 파일로 환경변수 관리

모든 패키지는 pypi.org에서 검색·문서 확인 가능. 패키지 설치 전 공식 문서와 GitHub 별점·최근 업데이트 날짜를 확인하는 습관이 중요하다.

---

🏭 가상환경(venv) — 프로젝트별 독립 환경 만들기

문제 상황: A 프로젝트는 requests 2.28이 필요하고, B 프로젝트는 requests 2.31이 필요합니다. 컴퓨터 전역에 하나만 설치하면 둘 중 하나가 망가집니다. 이 문제를 해결하는 것이 가상환경(Virtual Environment)입니다. 프로젝트마다 독립된 파이썬 환경을 만들어 패키지 버전을 따로 관리합니다.

 

터미널 (macOS/Linux)

# ① 가상환경 생성 — python -m venv 이름
python -m venv .venv          # .venv 폴더에 가상환경 생성

# ② 가상환경 활성화
# macOS / Linux
source .venv/bin/activate

# ③ 활성화 확인 — 터미널 앞에 (.venv) 가 붙음
(.venv) $ python --version   # 가상환경 파이썬
(.venv) $ pip list           # 가상환경 전용 패키지 목록

# ④ 패키지 설치 — 가상환경 전용으로 설치됨
(.venv) $ pip install requests pandas

# ⑤ requirements.txt 저장 (팀 공유·배포용)
(.venv) $ pip freeze > requirements.txt

# ⑥ 가상환경 비활성화
(.venv) $ deactivate

 

터미널 (Windows)

# ① 생성
python -m venv .venv

# ② 활성화 (Windows)
.venv\Scripts\activate

# PowerShell에서 권한 오류 시
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

💡

가상환경 Best Practice 프로젝트마다 가상환경을 만드는 것이 기본

• .gitignore에 .venv/ 추가: 가상환경 폴더를 Git에 올리지 말 것 — 용량이 크고 OS마다 다름
• requirements.txt는 꼭 공유: pip freeze > requirements.txt로 저장하고 Git에 포함
• 팀원 환경 복원: pip install -r requirements.txt로 동일 환경 재구성
• 더 편한 도구: pipenv, poetry, uv는 가상환경+패키지를 한번에 관리하는 도구로 최근 많이 쓰임

프로젝트 구조 예시
my_project/
├── .venv/ ← 가상환경 (Git 제외)
├── .gitignore
├── requirements.txt ← 패키지 목록 (Git 포함)
├── main.py
└── utils.py

---

📁 패키지 구조 직접 만들기

 

패키지 폴더 구조 예시

# 폴더 구조
mypackage/
├── __init__.py      # 이 폴더가 패키지임을 알리는 파일 (내용 없어도 됨)
├── math_utils.py
├── string_utils.py
└── io_utils.py

# __init__.py — 패키지 초기화, 외부에 노출할 것 정의
# mypackage/__init__.py
from .math_utils   import add, subtract
from .string_utils import capitalize_all
__version__ = "1.0.0"

# 사용법
from mypackage import add        # __init__.py에 노출된 것만
from mypackage.math_utils import multiply  # 서브 모듈 직접 접근
print(mypackage.__version__)   # 1.0.0

---

📝 11편 실습 문제

실습 1 — 유틸리티 모듈 만들기

• converter.py 모듈 작성: 온도 변환(℃↔℉), 킬로미터↔마일 변환 함수 포함
• if __name__ == "__main__": 블록에서 모든 함수 테스트
• main.py에서 converter 모듈을 import해 활용

실습 2 — 표준 라이브러리 활용

• datetime으로 오늘 날짜, 100일 후 날짜 출력
• collections.Counter로 문장에서 가장 많이 등장한 단어 Top 3 출력
• random.sample()로 1~45 숫자 중 6개 뽑기(로또 시뮬레이션)

 

practice_11.py — 예시 답안

# 실습 1 — converter.py
def celsius_to_fahrenheit(c: float) -> float:
    return c * 9 / 5 + 32

def fahrenheit_to_celsius(f: float) -> float:
    return (f - 32) * 5 / 9

def km_to_mile(km: float) -> float:
    return km * 0.621371

if __name__ == "__main__":
    print(celsius_to_fahrenheit(100))   # 212.0
    print(fahrenheit_to_celsius(32))    # 0.0
    print(km_to_mile(100))              # 62.1371

# 실습 2 — 표준 라이브러리
from datetime import datetime, timedelta
from collections import Counter
import random

# 날짜 계산
today     = datetime.now().date()
day100    = today + timedelta(days=100)
print(f"오늘: {today}, 100일 후: {day100}")

# 단어 빈도 Top 3
sentence = "python is fun python is great python is easy"
cnt = Counter(sentence.split())
print("Top 3:", cnt.most_common(3))
# Top 3: [('python', 3), ('is', 3), ('fun', 1)]

# 로또 시뮬레이션
lotto = sorted(random.sample(range(1, 46), 6))
print(f"로또 번호: {lotto}")   # 예: [3, 12, 24, 31, 38, 42]

11편 핵심 요약

• 모듈: .py 파일 하나 = 모듈 / 함수·클래스·변수를 담아 재사용
• 패키지: __init__.py가 있는 폴더 = 패키지 / 여러 모듈의 묶음
• import 4가지: import 모듈 / from 모듈 import 이름 / import 모듈 as 별명 / from 모듈 import *(비권장)
• __name__: 직접 실행 시 "__main__" / import 시 모듈명 / if __name__ == "__main__": 패턴 필수
• 표준 라이브러리: 설치 없이 즉시 사용 / os·sys·datetime·random·collections·json 등
• pip 핵심 명령: install / uninstall / list / freeze / install -r requirements.txt
• 가상환경 venv: 프로젝트마다 독립 환경 / .venv는 gitignore / requirements.txt는 Git 포함
• 가상환경 명령: python -m venv .venv → source .venv/bin/activate → deactivate

다음 편 예고 12편 — 파이썬으로 엑셀·CSV 다루기

openpyxl / pandas / 데이터 읽기·쓰기·필터링 / 실무 자동화

🐍

---

※ 본 포스팅은 Python 3 공식 문서(docs.python.org)의 모듈·패키지·pip 레퍼런스를 기반으로 작성된 학습용 콘텐츠입니다. 코드 예시는 Python 3.10 이상 환경에서 테스트되었습니다.