파이썬 모듈과 패키지 완벽 정리: import부터 가상환경까지

목차

• 1. 모듈과 패키지가 뭔가요?
• 2. 실전에서 쓰이는 import 3가지 방식
• 3. 설치 없이 바로 쓰는 표준 라이브러리 BEST 5
• 4. pip와 가상환경(venv)으로 외부 패키지 관리하기
• 5. 나만의 모듈 만들기와 순환 참조 주의사항
• 6. 모듈 import 에러와 초보자 단골 실수 극복하기
• 자주 묻는 질문

1. 모듈과 패키지가 뭔가요?

파이썬으로 코딩을 시작하고 기능이 조금씩 늘어나다 보면, 파일 하나가 수백 줄에서 수천 줄까지 금방 길어지는 순간을 맞이하게 돼요. 코드가 이렇게 길어지면 원하는 기능을 찾기도 힘들고, 나중에 수정하려고 할 때 어디를 손대야 할지 막막해지죠. 이때 코드를 성격과 기능별로 쪼개서 예쁘게 저장해 두고, 필요할 때마다 블록 장난감처럼 조립해서 쓰면 참 편하겠죠? 파이썬에서는 이걸 모듈과 패키지라는 개념으로 깔끔하게 해결해요.

쉽게 말해 모듈은 파이썬 코드가 작성된 하나의 .py 파일이에요. 이 단일 파일 안에 여러분이 만든 변수나 함수, 클래스 등을 차곡차곡 모아두는 거죠. 마치 책의 한 챕터처럼 생각하면 이해가 빠를 거예요. 그리고 이런 모듈 여러 개를 관련 있는 주제끼리 묶어둔 폴더를 우리는 패키지라고 불러요. 여러 챕터가 모여서 한 권의 책을 이루는 것과 똑같은 원리예요.

아래는 현업에서 프로젝트를 구성할 때 볼 수 있는 전형적인 파이썬 패키지의 폴더 구조 예시예요. 어떻게 생겼는지 한눈에 살펴볼까요?

my_game_package/          # 게임 관련 모듈을 모아둔 패키지(폴더)예요
    __init__.py           # 파이썬에게 "이 폴더는 단순한 폴더가 아니라 패키지야"라고 알려주는 파일
    character_module.py   # 캐릭터 이동이나 공격 같은 코드가 있는 모듈(파일)
    item_module.py        # 아이템 획득, 사용 효과 등의 코드가 있는 모듈(파일)

위 구조를 보면 폴더 안에 __init__.py라는 특이한 이름의 파일이 보일 거예요. 이 파일의 역할이 궁금하시죠?

2. 실전에서 쓰이는 import 3가지 방식

다른 사람이 정성껏 만들어둔 모듈이나, 내가 이전에 쪼개서 만들어둔 모듈을 현재 작업 중인 코드로 불러올 때 import라는 키워드를 써요. 파이썬을 다루면서 정말 셀 수 없이 많이 치게 될 단어 중 하나예요. 그런데 무작정 불러오기보다는, 상황에 따라 세 가지 방식을 적절히 골라 쓰는 것이 실력자의 조건이랍니다.

첫째, 모듈 전체를 통째로 가져오는 import 모듈명 방식이에요. 이 방식은 어떤 기능을 쓸 때마다 앞에 모듈 이름을 붙여야 해서 타자를 조금 더 쳐야 하지만, 이 기능이 도대체 어디서 온 건지 출처가 아주 명확해서 가장 많이 사랑받는 표준적인 방법이에요.

둘째, 모듈에서 내가 딱 필요한 특정 기능(함수나 클래스)만 쏙 빼오는 from 모듈명 import 이름 방식이에요. 이 방식을 쓰면 코드를 작성할 때마다 매번 모듈 이름을 앞에 안 붙여도 돼서 손가락이 편하고 코드도 짧아지죠.

셋째, 모듈 이름이 유난히 길거나 타자 치기 귀찮을 때 별명을 지어주는 import 모듈명 as 별칭 방식이에요. 데이터를 다룰 때 많이 쓰는 pandas를 pd로, numpy를 np로 부르는 것이 업계의 국룰 같은 예시예요.

설명만 들으면 감이 잘 안 올 수 있으니 세 가지 방식을 실제 파이썬 코드로 비교해 볼게요.

# 방식 1: 모듈 전체를 정직하게 가져오기
import math

# math 모듈 안에 있는 제곱근(sqrt) 함수를 사용할 때 출처를 밝혀줘요
print(math.sqrt(16))  # 출력: 4.0 

# 방식 2: 수많은 기능 중 특정 함수만 콕 집어 가져오기
from math import ceil, floor

# math.ceil 이라고 길게 쓰지 않고 바로 함수 이름만 써서 편해요
print(ceil(3.2))      # 출력: 4 (올림)
print(floor(3.9))     # 출력: 3 (내림)

# 방식 3: 긴 이름 대신 짧은 별명 붙여서 가져오기
import random as rd

# random 이라는 단어 대신 rd라는 짧은 이름으로 접근해요
print(rd.randint(1, 10))  # 1부터 10 사이의 랜덤한 정수를 뽑아줘요

코드를 보다 보면 초보자분들은 “그럼 무조건 2번 방식이 타이핑할 일도 적고 훨씬 편하고 좋은 거 아니야?”라고 생각하기 쉬워요. 실제로 처음엔 다들 그렇게 코드를 짜요.

3. 설치 없이 바로 쓰는 표준 라이브러리 BEST 5

세상에 수많은 프로그래밍 언어가 있지만 그중에서도 파이썬이 독보적으로 인기 있는 이유는 바로 ‘건전지 포함(Batteries Included)’이라는 훌륭한 철학 때문이에요. 장난감을 샀는데 건전지가 안 들어있어서 바로 못 놀면 짜증 나잖아요? 파이썬은 설치하는 순간 이미 강력하고 쓸만한 모듈들이 내부에 수두룩하게 탑재되어 있어요. 우리는 이걸 표준 라이브러리라고 불러요.

별도의 다운로드나 설치 과정이 전혀 필요 없고, 그저 코드 최상단에 import 한 줄만 적어주면 당장 강력한 기능들을 마음껏 쓸 수 있어요. 그중에서도 실전 프로젝트나 코딩 테스트에서 숨 쉬듯 쓰이는 5가지 필수 라이브러리(math, random, datetime, os, sys)의 핵심 기능을 꾹꾹 눌러 담아 모아봤어요.

import math
import random
from datetime import datetime, timedelta
import os
import sys

# 1. math: 복잡한 수학 계산을 도와줘요
# 원주율(pi) 상수와 거듭제곱(pow) 함수를 이용해 원의 넓이를 쉽고 정확하게 구해요
area = math.pi * math.pow(5, 2)
print(f"반지름 5인 원의 넓이: {area:.2f}")

# 2. random: 예측할 수 없는 난수와 무작위 뽑기를 담당해요
fruits = ["사과", "바나나", "포도", "딸기"]
# choice는 중복을 허락해서 무작위로 1개를 쏙 뽑고, 
# sample은 중복 없이 여러 개를 한 번에 뽑을 때 완벽해요
print("오늘의 간식:", random.choice(fruits))
print("이번 주 로또 번호:", sorted(random.sample(range(1, 46), 6)))

# 3. datetime: 까다로운 날짜와 시간 다루기의 끝판왕이에요
now = datetime.now()
# timedelta를 쓰면 번거로운 날짜 더하고 빼기 계산을 너무나 쉽게 해줘요
thirty_days_later = now + timedelta(days=30)
print("오늘부터 30일 뒤의 날짜:", thirty_days_later.strftime("%Y-%m-%d"))

# 4. os: 운영체제와 소통하며 파일 경로를 똑똑하게 관리해요
# 윈도우는 '\', 맥은 '/' 처럼 경로 구분자가 다른데, join이 알아서 운영체제에 맞춰 결합해줘요
safe_path = os.path.join("my_folder", "data.txt")
print("안전하게 결합된 파일 경로:", safe_path)

# 5. sys: 파이썬이 실행되는 시스템 정보를 다뤄요
# 프로그램이 돌아가는 현재 파이썬 버전을 확인할 수 있어요
print("현재 파이썬 버전:", sys.version.split()[0])

위 코드에서 가장 눈여겨보고 내 것으로 만들어야 할 건 random 모듈의 choice와 sample의 결정적 차이, 그리고 파일 경로를 합쳐주는 os.path.join이에요.

특히 초보자분들이 파일 경로를 만들 때 문자열 더하기 기호(+)로 대충 합치는 경우가 정말 많은데, 이렇게 하면 내 컴퓨터에서는 잘 돌아가다가 나중에 윈도우 쓰는 친구한테 보내거나 서버에 올렸을 때 백발백중 경로 에러가 터져요. 처음부터 무조건 os.path.join을 쓰는 습관을 들이는 것이 미래의 나를 살리는 길이에요.

4. pip와 가상환경(venv)으로 외부 패키지 관리하기

기본 탑재된 라이브러리도 훌륭하지만, 현업에서 개발하다 보면 그것만으로는 한계가 오기 마련이에요. 웹 크롤링을 하거나 AI 모델을 돌리려면 전 세계 수많은 천재 개발자들이 이미 잘 만들어둔 외부 패키지를 다운로드해서 써야 하거든요. 이때 사용하는 마법의 도구가 바로 pip예요. 스마트폰에서 앱을 다운받을 때 쓰는 앱스토어나 플레이스토어 같은 역할을 한다고 생각하면 편해요.

그런데 신나서 이것저것 패키지를 컴퓨터 전체에 설치하다 보면 치명적인 문제가 생겨요. A 프로젝트는 특정 패키지의 구버전을 필요로 하고, 새로 시작한 B 프로젝트는 최신 버전을 요구하는 식으로 얽히고설켜서 심각한 충돌이 발생하는 일이 잦아요.

이런 골치 아픈 문제를 사전에 완벽히 차단하기 위해 파이썬 표준 라이브러리 venv를 활용한 가상환경 적용 방법을 반드시 숙지해야 해요. 프로젝트마다 완전히 독립된 빈 방, 즉 가상환경을 만들어주고 오직 그 방 안에만 필요한 패키지를 설치하는 것이 실무의 기본 수칙이에요.

터미널(또는 명령 프롬프트)을 열고 가상환경을 만들어서 패키지를 설치하는 전체 흐름을 단계별로 따라 해 볼까요?

python -m venv myenv

# Mac / Linux 기준
source myenv/bin/activate

# Windows 기준
myenv\Scripts\activate

pip install requests==2.31.0

# 현재 상태를 백업해요
pip freeze > requirements.txt

# 팀원은 이렇게 한 번에 설치해요
pip install -r requirements.txt

터미널 프롬프트 앞에 (myenv)처럼 내가 만든 가상환경 이름이 예쁘게 떠 있다면 성공적으로 나만의 방에 들어온 거예요. 앞으로 새로운 파이썬 프로젝트를 시작할 때는 다른 생각 하지 말고 무조건 venv로 가상환경부터 만들고 시작한다고 외워두세요.

5. 나만의 모듈 만들기와 순환 참조 주의사항

남의 코드를 가져다 쓰는 법을 마스터했으니, 이제 내가 짠 멋진 코드를 남들도 쓸 수 있게 직접 모듈로 만들어 볼 차례예요. 사실 모듈을 만든다고 해서 거창한 설정이 필요한 건 절대 아니에요. 그냥 바탕화면이나 폴더에 .py 확장자를 가진 파일을 하나 만들고 그 안에 함수나 클래스를 적어두면, 그게 바로 당당한 파이썬 모듈이 되는 거랍니다.

그런데 초보자들이 열정에 불타서 파일을 기능별로 막 쪼개다 보면 아주 흔하게 마주치는 거대한 장벽이 하나 있어요. 바로 A 파일이 B 파일의 기능을 부르고, B 파일은 다시 A 파일의 기능을 부르는 꼬임 현상이에요. 개발자들은 이걸 순환 참조(Circular Import)라고 불러요. 파일 구조를 짜기 전에 파이썬 모듈 패키지 생성 시 순환 참조 주의사항을 꼭 읽어보고 설계 단계부터 밑그림을 잘 그리는 게 중요해요.

우선 나만의 모듈을 만들고 호출하는 아주 정상적이고 바람직한 구조를 보여드릴게요.

# --- math_utils.py (내가 땀 흘려 만든 수학 모듈) ---
def calculate_average(numbers):
    # 만약 넘어온 숫자 리스트가 텅 비어있으면 0을 안전하게 반환해요
    if not numbers:
        return 0
    # 다 더해서 개수로 나누는 평균 공식을 적용해요
    return sum(numbers) / len(numbers)

# --- main.py (실제로 프로그램을 실행할 메인 파일) ---
# 같은 폴더 안에 얌전히 있는 math_utils 모듈을 불러와요
import math_utils

scores = [80, 90, 100]
# 모듈이름.함수이름() 형태로 호출해서 결과를 얻어내요
avg = math_utils.calculate_average(scores)
print(f"세 과목의 평균 점수: {avg}")

6. 모듈 import 에러와 초보자 단골 실수 극복하기

튜토리얼을 보며 잘 따라오다가 터미널 창에 갑자기 빨간색 에러 메시지가 주르륵 뜨면 정말 가슴이 철렁 내려앉죠? 모듈과 관련해서 코딩 입문자들이 가장 자주 마주치는 악명 높은 에러 두 가지가 바로 ModuleNotFoundError와 ImportError예요.

이 에러들을 만났을 때는 당황하지 말고 파이썬 import 모듈 예외 처리 및 트러블슈팅 가이드를 천천히 참고하면서 내가 놓친 부분이 없는지 점검해 보세요. 코드에 사소한 오타가 있는지, 패키지를 열심히 설치한 가상환경을 켜지도 않고 실행한 건 아닌지 확인해 보는 게 최우선이에요.

특히 처음 공부하시는 분들이 무조건 한 번씩은 겪게 되는 대표적인 실수 두 가지를 코드로 정리해 봤으니 눈으로 익혀두세요.

# 실수 1: 터미널에서 설치한 이름과 코드에서 부르는 이름이 다를 때
# 터미널 창에 pip install Pillow 라고 열심히 쳐서 이미지 패키지를 설치해놓고
# 코드에서 아래처럼 치면 모듈을 찾을 수 없다고 에러가 나요.
# import Pillow (X)

import PIL # (O) - 반드시 패키지 제작자가 정해둔 진짜 이름으로 불러와야 해요.

# 실수 2: 파일 경로를 그냥 문자열 더하기로 대충 만들 때
# 특히 윈도우 환경에서 아래 코드를 실행하면 슬래시 방향 문제로 에러가 날 확률이 아주 높아요.
# bad_path = "images" + "/" + "profile.png" (X)

import os
# 앞서 배웠던 os.path.join을 쓰면 내가 현재 쓰고 있는 컴퓨터 운영체제에 맞춰서
# 알맞은 슬래시를 찰떡같이 넣어주니까 에러 걱정이 사라져요.
good_path = os.path.join("images", "profile.png") # (O)

내가 터미널에 분명히 pip install로 설치를 완료했는데도 코드를 실행할 때 모듈을 찾을 수 없다는 에러가 끈질기게 뜬다면, 십중팔구 가상환경을 activate로 활성화하지 않은 엉뚱한 상태에서 실행했거나 코드 상의 영어 스펠링 오타일 확률이 99%예요. 머리를 식히고 차분하게 터미널 창에 떠 있는 경로와 오타를 하나씩 짚어가며 확인해 보세요.

자주 묻는 질문

Q. pip로 분명히 패키지를 설치했는데 예전에 잘 돌아가던 다른 프로젝트 코드가 갑자기 안 돌아가요. 왜 그런가요?

시스템 전역(컴퓨터 전체)에 패키지를 무분별하게 그냥 설치하셨을 확률이 굉장히 높아요. A 프로젝트는 이 패키지의 1.0 버전에 맞춰져 있는데, 다른 프로젝트를 하려고 2.0 버전으로 업데이트해 버리면 A 프로젝트 코드가 고장 날 수 있거든요. 이런 끔찍한 버전 충돌을 막으려면 앞서 설명해 드린 파이썬 내장 모듈인 venv를 사용해서 프로젝트마다 완전히 독립된 가상환경 방을 구축하고 딱 그 안에만 패키지를 설치하는 습관을 들여야 해요.

Q. 분명히 패키지 설치를 완료했는데 실행만 하면 ModuleNotFoundError가 계속 뜹니다. 사람 미치겠는데 어떻게 해결하나요?

숨을 깊게 들이마시고 딱 세 가지만 순서대로 확인해 보세요. 첫째, 패키지를 설치했던 그 가상환경이 켜진 상태(터미널 앞에 이름이 떠 있는 상태)에서 파이썬 코드를 실행했는지 확인하세요. 둘째, 터미널에 입력한 pip install [이름]과 코드 상단에 적은 import [이름]이 일치하는지 확인하세요. Pillow를 설치하고 PIL로 부르는 것처럼 설치 이름과 호출 이름이 다른 얄미운 패키지들이 종종 있어요. 셋째, 단순한 영어 스펠링 오타나 대소문자 실수가 없는지 꼼꼼히 체크해 보세요.

Q. 제가 직접 만든 두 개의 모듈이 서로의 함수를 import 하도록 작성했더니 알 수 없는 에러가 발생합니다. 원인이 도대체 무엇인가요?

두 모듈이 서로를 교차로 불러오려고 할 때 발생하는 전형적이고 골치 아픈 ‘순환 참조(Circular Import)’ 현상이에요. 파이썬이 첫 번째 파일을 끝까지 읽기도 전에 두 번째 파일을 부르고, 두 번째 파일은 다시 첫 번째 파일을 부르는 행위를 반복하다 보니 완전히 꼬여버린 거죠. 이럴 때는 두 모듈이 공통으로 사용하는 함수를 아예 새로운 세 번째 모듈로 분리해서 가져오거나, 정 안 되겠다면 import 문을 파일 맨 위가 아닌 함수 내부 안으로 숨겨서 필요할 때만 부르도록 구조를 고쳐야 해요. 실무에서는 보통 공통 모듈로 분리하는 첫 번째 방법이 가장 깔끔하고 권장되는 방법이랍니다.

이 글이 마음에 드세요?

RSS 피드를 구독하세요!