What is the difference between a module and a package?

A module is a single .py file; a package is a directory that groups modules.

import vs from ....import?

`import module` binds the module object; `from module import name` imports specific names into the current namespace.

It marks a directory as a package (optional in Python 3.3+ namespace packages, but still useful for explicit packages).

[2026] Python Modules and Packages | import, pip, and Virtual Environments Explained

2026년 3월 28일 · 16분 읽기 · 수정 2026년 3월 28일 Beginner Tutorial

이 글의 핵심

Complete guide to Python modules and packages: import styles, __init__.py, pip and PyPI, requirements.txt, venv, sys.path, and fixing import errors—with examples.

Introduction

“Split code into modules”

Modules and packages are how you structure code and reuse it across projects.

1. What is a module?

Definition

A module is a .py file containing Python code. You can put functions, classes, and variables in a module and import them elsewhere. Why use modules?

Reuse the same code in many places
Namespaces to avoid name clashes
Maintenance by splitting features into files

Creating a module

Example: a small math utilities module 다음은 python를 활용한 상세한 구현 코드입니다. 함수를 통해 로직을 구현합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# math_utils.py (module file)
"""
Math utility functions.
"""
def add(a, b):
    """Return a + b."""
    return a + b
def multiply(a, b):
    """Return a * b."""
    return a * b
def power(base, exponent):
    """Return base ** exponent."""
    return base ** exponent
# Module-level constants
PI = 3.14159
E = 2.71828
# Runs only when this file is executed directly
if __name__ == '__main__':
    print("math_utils self-test")
    print(f"2 + 3 = {add(2, 3)}")
    print(f"2 * 3 = {multiply(2, 3)}")

Using a module

다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# main.py (imports the module)
import math_utils
# Call functions on the module
result1 = math_utils.add(3, 5)
print(result1)  # 8
result2 = math_utils.multiply(4, 7)
print(result2)  # 28
# Module constants
print(math_utils.PI)  # 3.14159
# Circle area
radius = 5
area = math_utils.PI * math_utils.power(radius, 2)
print(f"Area of circle with radius {radius}: {area}")  # 78.53975

How `name` works

다음은 python를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# math_utils.py
print(f"__name__ = {__name__}")
if __name__ == '__main__':
    print("This module was run as the main program")
else:
    print("This module was imported")
# When you run `python math_utils.py`:
#   __name__ = __main__
#   This module was run as the main program
# When you `import math_utils`:
#   __name__ = math_utils
#   This module was imported

Module search path

Python looks for modules in this order: 아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

import sys
for path in sys.path:
    print(path)
# Typical order:
# 1. Directory of the script you run
# 2. Entries from PYTHONPATH
# 3. Standard library directories
# 4. site-packages (third-party installs from pip)
# Add a path at runtime
sys.path.append('/custom/path')

2. import syntax

Four common patterns

There are four main ways to import. Each has trade-offs—pick what fits the situation.

1) Import the whole module

아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

import math
print(math.sqrt(16))  # 4.0
print(math.pi)  # 3.141592653589793
print(math.factorial(5))  # 120
# Pros:
# - Clear provenance (math.sqrt comes from math)
# - Fewer name collisions
# Cons:
# - More typing (prefix every call)

When to use

You call several functions from the module
You want readers to see where names come from

2) Import specific names

아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

from math import sqrt, pi, factorial
print(sqrt(16))  # 4.0 (no math. prefix)
print(pi)
print(factorial(5))
# Pros:
# - Shorter call sites
# - Import only what you need
# Cons:
# - Less obvious where names come from
# - Easier to shadow or clash names

Name clash example 아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

from math import sqrt
from numpy import sqrt  # shadows math.sqrt!
print(sqrt(16))  # numpy.sqrt behavior (may differ from math)
# Fix: use aliases
from math import sqrt as math_sqrt
from numpy import sqrt as np_sqrt
print(math_sqrt(16))
print(np_sqrt(16))

When to use

You use a few names often and the context is obvious

3) Aliases

다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

import math as m
import numpy as np
import pandas as pd
print(m.sqrt(16))
print(np.array([1, 2, 3]))
print(pd.DataFrame({'a': [1, 2]}))
# Pros:
# - Shorter names for long modules
# - Keeps namespace + less typing
# - Community conventions (np, pd) improve readability
# Cons:
# - Non-standard aliases confuse readers

Common aliases 아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 코드를 직접 실행해보면서 동작을 확인해보세요.

import numpy as np          # ✅ idiomatic
import pandas as pd         # ✅ idiomatic
import matplotlib.pyplot as plt
import tensorflow as tf
import numpy as n           # ❌ non-standard
import pandas as p          # ❌ confusing

When to use

Long module names used many times
Libraries with a de-facto short name (numpy → np)

4) Star import (discouraged)

아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

from math import *
print(sqrt(16))
print(pi)
# Pros:
# - Very short at call sites
# Cons:
# - Unclear origin of names
# - High collision risk
# - Harder code review
# - Conflicts with PEP 8 guidance

Problem scenario 아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 코드를 직접 실행해보면서 동작을 확인해보세요.

from math import *
from statistics import *
# Both may define mean — which one wins?
result = mean([1, 2, 3, 4, 5])

When to use

Almost never in production (maybe in a quick REPL session)

Comparison table

Style	Syntax	Example	Pros	Cons	Typical use
Whole module	`import math`	`math.sqrt(16)`	Clear	Verbose	Many calls
From import	`from math import sqrt`	`sqrt(16)`	Short	Less clear	Few names
Alias	`import math as m`	`m.sqrt(16)`	Clear + short	Must remember alias	Long names
Star	`from math import *`	`sqrt(16)`	Shortest	Dangerous	Avoid

Relative vs absolute imports

Absolute import: full path from the project/package root. 아래 코드는 text를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# Layout:
# myproject/
# ├── main.py
# └── mypackage/
#     ├── __init__.py
#     ├── utils.py
#     └── core/
#         └── engine.py
# In mypackage/core/engine.py
from mypackage.utils import helper  # absolute

Relative import: relative to the current package. 아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 코드를 직접 실행해보면서 동작을 확인해보세요.

# In mypackage/core/engine.py
from ..utils import helper  # parent package
from . import config        # same package
# .  = current directory
# ...= parent
# ....= grandparent (rare)

Trade-offs 아래 코드는 text를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

Absolute:
✅ Clear and stable
❌ Renaming the top-level package touches many imports
Relative:
✅ Easier when moving subpackages
❌ Fails if you run a module as a plain script (python engine.py)

Guideline: prefer absolute imports; use relative imports inside a package when it helps.

3. Packages

What is a package?

A package is a directory of modules. Traditionally an __init__.py file marks the directory as a package (and can run initialization code). Why packages?

Hierarchy for related modules
Namespaces to avoid flat name clashes
Distribution as a single installable unit

Example layout

아래 코드는 text를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

myproject/
├── main.py
├── requirements.txt
└── mypackage/
    ├── __init__.py
    ├── module1.py
    ├── module2.py
    └── subpackage/
        ├── __init__.py
        └── module3.py
# Python 3.3+ can treat directories as namespace packages without __init__.py,
# but an explicit __init__.py is still common for regular packages.

Building a package

Step 1: create modules 다음은 python를 활용한 상세한 구현 코드입니다. 함수를 통해 로직을 구현합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# mypackage/math_ops.py
def add(a, b):
    """Addition."""
    return a + b
def subtract(a, b):
    """Subtraction."""
    return a - b
# mypackage/string_ops.py
def reverse(text):
    """Reverse a string."""
    return text[::-1]
def capitalize_words(text):
    """Title-case each word."""
    return ' '.join(word.capitalize() for word in text.split())

Step 2: __init__.py 다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# mypackage/__init__.py
# 실행 예제
"""
mypackage: small utility library.
"""
from .math_ops import add, subtract
from .string_ops import reverse, capitalize_words
__version__ = '1.0.0'
# __all__ controls `from mypackage import *`
__all__ = ['add', 'subtract', 'reverse', 'capitalize_words']
# Optional side effect on import
print(f"mypackage v{__version__} loaded")

Step 3: use the package 아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# main.py
import mypackage
print(mypackage.add(3, 5))
print(mypackage.reverse("Hello"))
from mypackage.math_ops import add
from mypackage.string_ops import reverse
print(add(10, 20))
print(reverse("Python"))
from mypackage import add, reverse
print(add(1, 2))

Roles of `init.py`

다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# 1) Empty file: marks directory as a package
# mypackage/__init__.py
# (empty)
# 2) Re-export symbols for shorter imports
# from .math_ops import add
# enables: from mypackage import add
# 3) Package initialization: logging, settings
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
logger.info("package init")
# 4) __all__ lists the public API
__all__ = ['add', 'subtract']

Subpackages

아래 코드는 text를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

myproject/
├── main.py
└── mypackage/
    ├── __init__.py
    ├── math_ops.py
    ├── string_ops.py
    └── advanced/
        ├── __init__.py
        ├── statistics.py
        └── algorithms.py

Using a subpackage 다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 함수를 통해 로직을 구현합니다, 조건문으로 분기 처리를 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# mypackage/advanced/statistics.py
def mean(numbers):
    """Arithmetic mean."""
    return sum(numbers) / len(numbers)
def median(numbers):
    """Median value."""
    sorted_nums = sorted(numbers)
    n = len(sorted_nums)
    mid = n // 2
    return sorted_nums[mid] if n % 2 == 1 else (sorted_nums[mid-1] + sorted_nums[mid]) / 2
# main.py
from mypackage.advanced.statistics import mean, median
data = [1, 2, 3, 4, 5]
print(f"mean: {mean(data)}")
print(f"median: {median(data)}")

4. The standard library

What is it?

The standard library ships with Python. No extra install—just import.

Frequently used modules

1) `os` — OS services

다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

import os
print(os.getcwd())
os.chdir('/path/to/directory')
os.mkdir("new_folder")
os.makedirs("parent/child/grandchild")
print(os.path.exists('file.txt'))
print(os.path.isfile('file.txt'))
print(os.path.isdir('folder'))
path = os.path.join('folder', 'subfolder', 'file.txt')
print(os.environ.get('PATH'))
os.environ['MY_VAR'] = 'value'
files = os.listdir('.')
print(files)

2) `datetime` — dates and times

다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

from datetime import datetime, timedelta, date, time
now = datetime.now()
print(now)
formatted = now.strftime("%Y-%m-%d %H:%M:%S")
print(formatted)
tomorrow = now + timedelta(days=1)
next_week = now + timedelta(weeks=1)
two_hours_ago = now - timedelta(hours=2)
print(f"Tomorrow: {tomorrow.strftime('%Y-%m-%d')}")
print(f"Next week: {next_week.strftime('%Y-%m-%d')}")
date_str = "2026-12-31 23:59:59"
parsed = datetime.strptime(date_str, "%Y-%m-%d %H:%M:%S")
print(parsed)
today = date.today()
print(today)
current_time = time(14, 30, 0)
print(current_time)

3) `random` — random numbers

다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

import random
print(random.randint(1, 10))
print(random.randrange(0, 10, 2))
print(random.random())
print(random.uniform(1.0, 10.0))
colors = ['red', 'blue', 'green', 'yellow']
print(random.choice(colors))
print(random.choices(colors, k=3))
print(random.sample(colors, k=2))
numbers = [1, 2, 3, 4, 5]
random.shuffle(numbers)
print(numbers)
random.seed(42)
print(random.randint(1, 100))

4) `json` — JSON

다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

import json
data = {"name": "Alice", "age": 25, "hobbies": ["reading", "movies"]}
json_str = json.dumps(data, ensure_ascii=False, indent=2)
print(json_str)
parsed = json.loads(json_str)
print(parsed['name'])
print(type(parsed))
with open('data.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, ensure_ascii=False, indent=2)
with open('data.json', 'r', encoding='utf-8') as f:
    loaded = json.load(f)
    print(loaded)

5) `sys` — interpreter and runtime

아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고, 에러 처리를 통해 안정성을 확보합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

import sys
print(sys.version)
# python script.py arg1 arg2
print(sys.argv)
print(sys.path)
# sys.exit(0)  # normal exit
# sys.exit(1)  # error exit

6) `pathlib` — object-oriented paths

다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

from pathlib import Path
current = Path.cwd()
print(current)
file_path = Path('folder') / 'subfolder' / 'file.txt'
print(file_path)
if file_path.exists():
    print("exists")
file_path.write_text("Hello, World!", encoding='utf-8')
content = file_path.read_text(encoding='utf-8')
print(content)
print(file_path.name)
print(file_path.stem)
print(file_path.suffix)
print(file_path.parent)
for file in Path('.').glob('*.py'):
    print(file)

5. pip and package management

What is pip?

pip installs and manages third-party packages from PyPI (the Python Package Index).

Common pip commands

다음은 bash를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

pip install requests
# pip will:
# 1. Find the package on PyPI
# 2. Download a release
# 3. Install dependencies
# 4. Place files under site-packages
pip install requests==2.28.0
pip install "requests>=2.28.0"
pip install "requests>=2.28.0,<3.0.0"
pip install --upgrade requests
pip install -U requests
pip show requests
pip uninstall requests
pip uninstall -y requests
pip list
pip list --outdated
pip freeze > requirements.txt
pip install -r requirements.txt

requirements.txt format

다음은 text를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# Pin exact versions (common in production)
requests==2.28.0
flask==2.3.0
pandas==2.0.0
# Minimum version
numpy>=1.24.0
# Range
django>=4.0.0,<5.0.0
# Web stack
flask==2.3.0
# Data stack
pandas==2.0.0
numpy==1.24.0
# Dev-only (often a separate file)
# requirements-dev.txt
pytest==7.3.0
black==23.3.0
flake8==6.0.0

Advanced pip usage

아래 코드는 bash를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

pip install -e .
# Editable install: changes in source are visible without reinstall
pip install git+https://github.com/user/repo.git
pip install git+https://github.com/user/repo.git@branch_name
pip install package-1.0.0-py3-none-any.whl
pip install requests flask pandas
pip install --no-cache-dir requests
pip install --user requests

pip troubleshooting

아래 코드는 bash를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

pip install --upgrade pip
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org requests
pip install --user requests
pip install --force-reinstall requests
pip check

6. Virtual environments (basics)

Using venv

아래 코드는 bash를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

python -m venv myenv
# Windows
myenv\Scripts\activate
# macOS / Linux
source myenv/bin/activate
pip install requests
deactivate

7. Virtual environments (in depth)

How venv works

다음은 bash를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

python -m venv myenv
# Common names: venv, .venv, env
# Layout:
# myenv/
# ├── Scripts/   # Windows
# ├── bin/       # Unix
# ├── Lib/
# └── pyvenv.cfg
# Windows PowerShell
myenv\Scripts\Activate.ps1
# Windows CMD
myenv\Scripts\activate.bat
# macOS / Linux
source myenv/bin/activate
# Prompt shows (myenv) when active
which python   # Unix
where python   # Windows
# Points at the interpreter inside the environment
pip install requests flask pandas
pip list
pip freeze > requirements.txt
deactivate

Typical workflow

다음은 bash를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

mkdir myproject
cd myproject
python -m venv venv
venv\Scripts\activate  # Windows
pip install flask sqlalchemy pytest
pip freeze > requirements.txt
echo "venv/" >> .gitignore
git add .
git commit -m "Initial commit"
git clone <repo>
cd myproject
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

Global vs virtual environment

	Global install	Virtual environment
Location	Python install dir	Project directory
Isolation	Shared across projects	Per project
Version conflicts	Possible	Avoided
Recommended for	System tools	Application work

8. Practical examples

Example 1: project skeleton

다음은 text를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

myproject/
├── venv/
├── src/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── file_utils.py
│   │   └── string_utils.py
│   └── models/
│       ├── __init__.py
│       └── user.py
├── tests/
│   ├── __init__.py
│   ├── test_utils.py
│   └── test_models.py
├── docs/
│   └── README.md
├── .gitignore
├── requirements.txt
├── requirements-dev.txt
├── setup.py
└── README.md

Example 2: simple web scraper

아래 코드는 text를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

web_scraper/
├── venv/
├── scraper/
│   ├── __init__.py
│   ├── main.py
│   ├── parser.py
│   └── storage.py
├── requirements.txt
└── README.md

다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 함수를 통해 로직을 구현합니다, 에러 처리를 통해 안정성을 확보합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# scraper/parser.py
# 필요한 모듈 import
import requests
from bs4 import BeautifulSoup
def fetch_page(url):
    """Download HTML for a URL."""
    response = requests.get(url, timeout=10)
    response.raise_for_status()
    return response.text
def parse_titles(html):
    """Extract heading text from HTML."""
    soup = BeautifulSoup(html, 'html.parser')
    titles = [h2.text.strip() for h2 in soup.find_all('h2')]
    return titles
# scraper/storage.py
import json
from pathlib import Path
def save_to_json(data, filename):
    """Write data to a JSON file."""
    with open(filename, 'w', encoding='utf-8') as f:
        json.dump(data, f, ensure_ascii=False, indent=2)
def load_from_json(filename):
    """Load JSON if the file exists."""
    if not Path(filename).exists():
        return None
    with open(filename, 'r', encoding='utf-8') as f:
        return json.load(f)
# scraper/__init__.py
"""
Web scraper package.
"""
from .parser import fetch_page, parse_titles
from .storage import save_to_json, load_from_json
__version__ = '1.0.0'
__all__ = ['fetch_page', 'parse_titles', 'save_to_json', 'load_from_json']
# scraper/main.py
from scraper import fetch_page, parse_titles, save_to_json
def main():
    url = 'https://example.com'
    
    print(f"Fetching: {url}")
    html = fetch_page(url)
    
    print("Parsing titles...")
    titles = parse_titles(html)
    
    save_to_json({'titles': titles}, 'output.json')
    
    print(f"Saved {len(titles)} titles")
if __name__ == '__main__':
    main()

requests==2.31.0
beautifulsoup4==4.12.0

다음은 간단한 bash 코드 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python -m scraper.main

9. Fixing import problems

Problem 1: ModuleNotFoundError

아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# ModuleNotFoundError: No module named 'mymodule'
# Cause 1: package not installed
# Fix: pip install mymodule
# Cause 2: path not on sys.path
import sys
print(sys.path)
sys.path.append('/path/to/module')
# Cause 3: wrong environment
import sys
print(sys.prefix)

Problem 2: Circular imports

다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 함수를 통해 로직을 구현합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# module_a.py
from module_b import func_b
def func_a():
    return func_b()
# module_b.py
from module_a import func_a  # circular!
# Fix 1: lazy import inside a function
def func_a():
    from module_b import func_b
    return func_b()
# Fix 2: shared module
# common.py with shared helpers
# Fix 3: refactor dependencies (best long-term)

Problem 3: Relative import errors

아래 코드는 python를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# ImportError: attempted relative import with no known parent package
# Cause: running a file inside a package directly
# python mypackage/module.py  # bad
# Fix: run as a module
# python -m mypackage.module
# Or use absolute imports:
# from mypackage.utils import helper

Problem 4: ImportError vs ModuleNotFoundError

아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 코드를 직접 실행해보면서 동작을 확인해보세요.

# ModuleNotFoundError: module missing entirely
# ImportError: module exists but the name does not
# from math import nonexistent_function
import math
print(dir(math))

10. Practical tips

1) Import order (PEP 8 style)

아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# Standard library
import os
import sys
from datetime import datetime
# Third party
import requests
import numpy as np
from flask import Flask
# Local application
from mypackage import utils
from mypackage.models import User

2) Optional dependencies

아래 코드는 python를 사용한 구현 예제입니다. 함수를 통해 로직을 구현합니다, 에러 처리를 통해 안정성을 확보합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

try:
    import numpy as np
    HAS_NUMPY = True
except ImportError:
    HAS_NUMPY = False
    print("NumPy not installed; using pure Python fallback.")
def process_data(data):
    if HAS_NUMPY:
        return np.array(data).mean()
    return sum(data) / len(data)

3) Lazy imports

아래 코드는 python를 사용한 구현 예제입니다. 함수를 통해 로직을 구현합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

def process_image(image_path):
    from PIL import Image  # import only when needed
    
    img = Image.open(image_path)
    return img.resize((100, 100))

4) `all`

아래 코드는 python를 사용한 구현 예제입니다. 함수를 통해 로직을 구현합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

def public_func():
    """Public API."""
    pass
def _private_func():
    """Internal by convention (_ prefix)."""
    pass
__all__ = ['public_func']
# from mymodule import *  # only public_func

5) Reloading during development

아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 코드를 직접 실행해보면서 동작을 확인해보세요.

import importlib
import mymodule
importlib.reload(mymodule)
# Avoid in production; debugging only

11. Exercises

Exercise 1: small utility package

Create this layout and use it: 다음은 간단한 text 코드 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

utils/
├── __init__.py
├── math_utils.py  # add, multiply
└── text_utils.py    # reverse, count_words

Exercise 2: requirements.txt

Write requirements.txt with:

requests (2.31.0)
flask (>=2.3.0,<3.0.0)
pandas (latest)

Exercise 3: standard library

Use datetime and random to:

Print the date 7 days from today
Draw 10 unique random integers from 1–100

Answers

다음은 python를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 함수를 통해 로직을 구현합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다. ```python # utils/math_utils.py # 함수 정의 및 구현 def add(a, b): return a + b def multiply(a, b): return a * b # utils/text_utils.py def reverse(text): return text[::-1] def count_words(text): return len(text.split()) # utils/__init__.py from .math_utils import add, multiply from .text_utils import reverse, count_words __all__ = ['add', 'multiply', 'reverse', 'count_words'] # main.py from utils import add, reverse print(add(3, 5)) print(reverse("Hello")) ``` ```text requests==2.31.0 flask>=2.3.0,<3.0.0 pandas ``` 아래 코드는 python를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 코드를 직접 실행해보면서 동작을 확인해보세요. ```python from datetime import datetime, timedelta import random today = datetime.now() after_7_days = today + timedelta(days=7) print(after_7_days.strftime("%Y-%m-%d")) random_numbers = random.sample(range(1, 101), k=10) print(random_numbers) ```

--- ## Summary ### Key takeaways 1. **Module**: a `.py` file; import to reuse code. 2. **Package**: directory of modules; `__init__.py` for regular packages. 3. **import styles**: whole module, from-import, alias, star (avoid star). 4. **Standard library**: `os`, `datetime`, `random`, `json`, `sys`, `pathlib`, … 5. **pip**: install from PyPI; pin versions for reproducibility. 6. **Virtual environments**: isolate dependencies per project (`venv`). 7. **requirements.txt**: record dependencies for installs. ### After you master the module system - **Reuse** code more confidently - **Structure** larger projects cleanly - **Collaborate** with clearer boundaries - **Ship** installs that match your environment ### Next steps - [Classes and objects](/blog/python-series-05-classes-en/) — OOP in Python - [Exception handling](/blog/python-series-08-exception-handling-en/) - [File handling](/blog/python-series-07-file-handling-en/) --- ## Related posts

이 글의 핵심

Introduction

“Split code into modules”

Modules and packages are how you structure code and reuse it across projects.

1. What is a module?

Definition

Creating a module

Using a module

How __name__ works

Module search path

2. import syntax

Four common patterns

1) Import the whole module

2) Import specific names

3) Aliases

4) Star import (discouraged)

Comparison table

Relative vs absolute imports

Guideline: prefer absolute imports; use relative imports inside a package when it helps.

3. Packages

What is a package?

Example layout

Building a package

Roles of __init__.py

Subpackages

4. The standard library

What is it?

Frequently used modules

1) os — OS services

2) datetime — dates and times

3) random — random numbers

4) json — JSON

5) sys — interpreter and runtime

6) pathlib — object-oriented paths

5. pip and package management

What is pip?

Common pip commands

requirements.txt format

Advanced pip usage

pip troubleshooting

6. Virtual environments (basics)

Using venv

7. Virtual environments (in depth)

How venv works

Typical workflow

Global vs virtual environment

8. Practical examples

Example 1: project skeleton

Example 2: simple web scraper

9. Fixing import problems

Problem 1: ModuleNotFoundError

Problem 2: Circular imports

Problem 3: Relative import errors

Problem 4: ImportError vs ModuleNotFoundError

10. Practical tips

1) Import order (PEP 8 style)

2) Optional dependencies

3) Lazy imports

4) __all__

5) Reloading during development

11. Exercises

Exercise 1: small utility package

Exercise 2: requirements.txt

Exercise 3: standard library

How `name` works

Roles of `init.py`

1) `os` — OS services

2) `datetime` — dates and times

3) `random` — random numbers

4) `json` — JSON

5) `sys` — interpreter and runtime

6) `pathlib` — object-oriented paths

4) `all`