파이썬 모듈과 임포트: import, from-import, pip, 패키지

파일 하나 = 모듈 하나

파이썬 코드가 단일 스크립트를 넘어서 커지면 여러 파일로 나누고 싶어져요. 파이썬의 모듈 시스템은 단순해요: 아무 .py 파일이나 자동으로 모듈이 되고, 이름으로 임포트할 수 있어요.

util.py 파일이 있다고 해볼게요:

# util.py
def greet(name):
    return f"Hello, {name}"

PI = 3.14159

같은 디렉터리의 다른 파일 main.py에서 이렇게 쓸 수 있어요:

# main.py
import util

print(util.greet("Ada"))
print(util.PI)

python3 main.py를 실행하면 파이썬이 util.py를 찾아서 한 번 실행하고, 최상위에 정의된 모든 것(함수, 변수, 클래스)을 util 모듈의 속성으로 노출해 줍니다.

임포트의 세 가지 형태

모듈 전체 임포트. 안의 것들은 모듈 이름을 통해 접근해요:

특정 이름만 임포트. 바로 쓸 수 있게 돼요:

별칭으로 임포트. 모듈 이름이 길거나, 두 모듈의 이름이 겹칠 때 유용해요:

import numpy as np
import pandas as pd

# 이제 np.array(...), pd.DataFrame(...) 처럼 씁니다.

네 번째 형태로 from math import *가 있는데, 네임스페이스로 _모든 것_을 끌어와요. REPL 실험 말고는 쓰지 마세요 — 이름이 어디서 왔는지 알 수 없고, 조용한 이름 충돌을 일으켜요.

임포트는 언제 실행되는가

파이썬은 임포트된 모듈의 최상위 코드를 프로그램 내 첫 임포트 시에 한 번 실행해요. 같은 모듈에 대한 이후 임포트는 이미 로드된 버전을 돌려줘요. 그래서 이런 경우:

# setup.py
print("setup module loading...")
VALUE = 42

# main.py
import setup
import setup  # 두 번 임포트했지만 — "loading"은 한 번만 찍힘
print(setup.VALUE)

"setup module loading..."은 한 번만 찍혀요. 이게 중요한 이유: 모듈 최상위에 사이드 이펙트(파일 열기, 출력 등)를 두면 임포트 시점에 실행되는데, 보통 원하는 게 아니에요. 그런 건 함수 안에 두세요.

표준 라이브러리

파이썬에는 방대한 표준 라이브러리가 함께 들어 있어요. 이미 몇 개는 보셨고요. 끊임없이 꺼내 쓰게 될 것들:

• math — sqrt, sin, log, pi나 e 같은 상수.
• random — 난수, 선택, 섞기.
• datetime — 날짜와 시간.
• json — JSON 읽기/쓰기.
• os, os.path — 파일 시스템 경로와 연산.
• pathlib — 현대적 경로 처리, os.path보다 종종 더 편해요.
• re — 정규 표현식.
• collections — 특수한 컬렉션 타입들(Counter, defaultdict, deque 등).
• itertools, functools — 이터레이터와 함수 헬퍼.
• csv — CSV 파일 읽고 쓰기.

표준 라이브러리는 이미 설치돼 있어요 — pip으로 따로 설치할 필요 없습니다.

서드파티 패키지와 pip

표준 라이브러리가 커버 못 하는 건 PyPI(Python Package Index)에 수십만 개의 패키지가 준비돼 있어요. pip으로 설치합니다:

pip install requests
pip install pandas
pip install --upgrade requests
pip uninstall requests

설치된 뒤에는 다른 모듈과 똑같이 임포트해요:

import requests

response = requests.get("https://api.example.com/data")
print(response.status_code)

제정신을 유지하기 위한 팁 몇 가지:

가상환경을 쓰세요

뭐든 전역에 설치하다 보면 고통이 시작돼요. 프로젝트마다 필요한 버전이 다르고, 어떤 패키지는 특정 파이썬 버전에 의존하고, 시스템에 따라 전역 설치에 관리자 권한이 필요하기도 해요. 가상환경(virtual environment) 은 한 프로젝트만을 위한 격리된 파이썬 설치예요:

python3 -m venv .venv
source .venv/bin/activate    # macOS/Linux
.venv\Scripts\activate       # Windows

pip install requests

venv가 활성화돼 있는 동안에는 pip이 시스템이 아니라 프로젝트 폴더에 설치해 줘요. 다 쓰고 나면 deactivate로 비활성화하세요.

의존성을 고정하세요

다른 사람(과 미래의 자신)이 같은 환경을 재현할 수 있게, 설치된 패키지 목록을 저장해 두세요:

pip freeze > requirements.txt

나중에는:

pip install -r requirements.txt

Poetry, pipenv, uv 같은 도구가 이걸 더 편하게 해주지만, 배우는 단계에서는 그냥 pip + requirements.txt 흐름도 괜찮아요.

나만의 모듈 작성하기

파일을 넘나들며 재사용하고 싶은 함수가 생기면, 자기만의 모듈에 담으세요. 이름 짓기 관례:

• 파일 이름은 lower_snake_case.py.
• 모듈 수준 함수와 변수도 lower_snake_case.
• 클래스는 PascalCase.

# shopping.py
PRICES = {"apple": 0.50, "bread": 2.00}

def total(items):
    return sum(PRICES[item] for item in items)

# main.py
from shopping import total, PRICES

print(total(["apple", "bread"]))
print(PRICES)

같은 폴더의 두 파일이 서로를 임포트하다 보면 실수로 _순환 참조_가 생길 수 있어요. 보통은 공통 코드를 세 번째 파일로 옮겨서 둘 다 그걸 임포트하게 고치면 됩니다.

패키지: 모듈들의 폴더

모듈이 몇 개를 넘으면 _패키지_로 묶으세요 — __init__.py 파일이 들어 있는 폴더예요:

myproject/
├── main.py
└── utils/
    ├── __init__.py
    ├── text.py
    └── numbers.py

그럼:

from utils.text import slugify
from utils import numbers

print(slugify("Hello, World"))
print(numbers.mean([1, 2, 3]))

__init__.py는 비어 있어도 돼요. 그 파일이 _있다는 사실_이 utils를 패키지로 만들어줍니다. 현대 파이썬은 __init__.py 없는 "네임스페이스 패키지"도 지원하지만, 시작할 때는 명시적인 버전이 더 명확해요.

임포트가 깨질 때 짧은 체크리스트

• "ModuleNotFoundError: No module named X". 패키지가 설치 안 돼 있거나, pip install한 인터프리터와 다른 파이썬으로 실행 중이거나. venv를 쓴다면 venv가 활성화돼 있는지 확인하세요.
• "ImportError: cannot import name Y from X". 모듈은 있는데 여러분이 요청한 이름이 없는 거예요. 오타 확인, 모듈의 실제 내용 확인.
• "Circular import". 두 모듈이 서로를 임포트하고 있어요. 공통 코드를 세 번째 모듈로 옮기세요.

다음: 서드파티 패키지 설치

자기 모듈만으로도 많은 걸 할 수 있지만, 실제 프로젝트는 대부분 PyPI에서 라이브러리를 가져다 써요 — requests, pandas, 테스트 프레임워크 같은 거요. 다음 페이지는 pip을 깔끔하게 써서 패키지를 설치하는 법, 그리고 프로젝트의 의존성을 기록하는 법을 다룹니다.