파이썬 초보자부터 중급자까지, 모듈과 패키지를 제대로 다루는 게 생각보다 어렵게 느껴지셨죠?
파이썬을 배우다 보면 어느 순간 '모듈'과 '패키지' 개념에서 멈칫하게 됩니다.
import 문을 썼는데도 오류가 나고, 폴더를 정리했는데도 모듈을 못 불러오는 상황.
한 번쯤 겪어보셨죠?
이럴 때마다 검색은 끝도 없고, Stack Overflow도 답이
명쾌하지 않죠. 심지어 디렉토리 구조까지 꼬이기 시작하면 프로젝트 전체가 터질
듯 복잡해져요. "도대체 왜 안 되는 거야?"라는 말이 절로 나옵니다. 사실 그
복잡함은 개념을 정확히 이해하지 못해서 생기는 문제예요. 이번 글에서는 모듈과
패키지의 본질부터 실전 사용법까지 쫙 정리해드립니다. 단순 문법이 아니라,
파이썬이 작동하는 '방식'을 알려드릴게요.
이 글 하나면 헷갈렸던 import
문제는 물론, __init__.py의 역할, 상대경로 vs 절대경로까지 싹 해결됩니다. 오직
실전 위주로만 구성했기에, 지금이 딱 필요한 타이밍이라면 절대 놓치지 마세요.
지금 바로 아래 목차를 따라가며 학습을 시작해보세요. 이미 알고 있던 분들도 "아,
이건 몰랐는데?" 싶은 인사이트를 얻으실 수 있을 거예요.
모듈이란 무엇인가?
파이썬에서 '모듈'은 하나의 .py
파일을 의미합니다. 이 파일 안에는 함수, 클래스, 변수 등 다양한 코드 요소들이
담길 수 있죠. 모듈을 사용하면 특정 기능을 따로 분리해 재사용할 수 있기
때문에 코드가 훨씬 깔끔해집니다. 예를 들어, 반복해서 쓰는 유틸리티 함수들을
하나의 모듈로 만들어두면, 여러 프로젝트에서 import
한 줄로 재활용이 가능하죠. 특히 규모가 큰 프로젝트일수록 모듈화를 잘 해두는
것이 개발 생산성을 높이는 핵심입니다.
모듈 가져오기 방법 총정리
| 형태 | 설명 | 예시 코드 |
|---|---|---|
| 기본 import | 모듈 전체를 가져옵니다. |
import math
|
| from import | 모듈에서 특정 요소만 선택합니다. |
from os import path
|
| as 별칭 사용 | 긴 모듈명을 짧게 줄입니다. |
import numpy as np
|
패키지 구조와 디렉토리 설계
패키지는 여러 개의 모듈을 하나의 폴더로 묶은 집합입니다. 즉, 폴더 하나가
패키지 단위가 되며, 그 안에 여러 개의 모듈(.py 파일)들이 들어갑니다. 이때 반드시 __init__.py라는 파일이 있어야 해당 디렉토리를 패키지로 인식합니다(파이썬 3.3
이상부터는 선택이지만 여전히 권장). 아래는 기본적인 구조예요:
-
project/
- main.py
-
mypackage/
- __init__.py
- module1.py
- module2.py
__init__.py의 역할과 활용법
__init__.py는 해당 디렉토리를 파이썬 패키지로 인식하도록
만들어주는 파일이에요. 초기에는 꼭 있어야 했지만, Python 3.3부터는 선택
사항으로 바뀌었죠. 하지만 여전히
패키지 초기화 작업이나,
하위 모듈의 기본 import 설정
등을 위해 유용하게 사용됩니다. 예를 들어 __init__.py에 하위
모듈을 미리 import 해두면, 외부에서 패키지를 호출할 때 편리해져요.
| 활용 방식 | 설명 |
|---|---|
| 패키지 초기화 | 초기 실행 시 필요한 설정 코드 실행 |
| 공용 모듈 노출 |
from .module import * 형태로 외부에 공개
|
상대경로 vs 절대경로 import
import 문을 사용할 때, 상대경로(from . import module)와 절대경로(from mypackage import module) 중 어떤 걸 써야 할지 고민되셨죠? 각각 장단점이 있습니다. 절대경로는
명확하고 외부에서도 사용하기 좋아요. 반면, 상대경로는 내부 모듈 간 참조 시
유용하죠. 중요한 건 일관성! 하나의 프로젝트 안에서는 한 방법을 통일해서 쓰는
게 유지보수에 훨씬 좋습니다.
모듈화를 통한 프로젝트 관리 팁
파이썬 프로젝트가 커질수록 '모듈화'는 선택이 아닌 필수가 됩니다. 잘게 나눈 모듈은 테스트도 쉬워지고, 팀원 간 협업도 원활하죠. 아래 리스트를 참고해서 모듈화를 실천해보세요.
- 하나의 파일에는 하나의 기능만
- utils, config 등 공용 모듈 분리
- 폴더 이름은 기능 단위로 명확하게
- 패키지마다 __init__.py 파일 유지
sys.path에 해당 경로가 포함되어 있는지 확인해보세요. 프로젝트 루트 폴더를 잘못 설정하면 모듈을 찾지 못할 수 있습니다.
파이썬 3.3 이상에서는 선택사항이지만, 명시적으로 패키지 구조를 표현하고 초기화 코드를 넣기 위해 여전히 많이 사용됩니다.
패키지 내부의 모듈끼리 import할 때 주로 사용됩니다. 다만, 외부 호출 환경에서는 에러가 날 수 있으므로 조심하세요.
동일한 이름의 모듈이 여러 개 있을 경우, 먼저 sys.path 상단에 위치한 폴더의 모듈이 우선됩니다. 이름 중복은 피하는 게 좋아요.
PEP8 권장 기준에 따르면 표준 라이브러리, 서드파티, 로컬 모듈 순으로 블록을 나누고, 각 블록은 알파벳 순으로 정렬하는 게 좋습니다.
__all__은 from module import * 할 때 import 대상이 될 항목을
제한하는 데 사용됩니다. 공개할 항목이 정해져 있을 때 선언해 주세요.
이제 파이썬의 모듈과 패키지 개념이 훨씬 선명하게 다가오셨을 거예요. 혼란스러웠던 import 문, 구조 잡기가 어려웠던 디렉토리 구성까지 이 글로 한 방에 정리되셨길 바랍니다. 저도 예전엔 정말 답답했는데, 이렇게 정리해놓고 보니까 "아, 이게 이렇게 쉬운 거였어?" 싶더라고요. 여러분도 꼭 한번 프로젝트에 적용해보시고, 진짜 효율적인 코드 관리의 세계를 경험해보세요. 오늘도 코드 한 줄, 실력 한 뼘 성장하셨길 바랍니다 :)
