Python Modules & Packages Tutorial

The Story That Explains Modules and Packages 🧰Modules और Packages समझाने वाली कहानी 🧰一个讲清模块与包的故事 🧰

A module is a single Python file. A package is a folder of modules. The import statement is how one file borrows code from another. These three ideas let you grow from one script to a whole system.

Module एक Python file है। Package modules का एक folder है। import statement वह तरीका है जिससे एक file दूसरी से code उधार लेती है। ये तीन विचार आपको एक script से पूरे system तक ले जाते हैं।

模块 是一个 Python 文件。包 是由模块组成的文件夹。import 语句是一个文件向另一个文件借用代码的方式。这三个概念让你从一个脚本成长为一整个系统。

Script vs Module vs Package 🗂️Script बनाम Module बनाम Package 🗂️脚本、模块与包 🗂️

Your First Module — A 90-Second Walkthrough ⏱️आपका पहला Module — 90 सेकंड में ⏱️你的第一个模块 — 90 秒上手 ⏱️

The smallest possible module: two files in the same folder. Then run python main.py.

सबसे छोटा module: एक ही folder में दो files। फिर python main.py चलाएँ।

最小的模块：同一文件夹中的两个文件。然后运行 python main.py。

# math_tools.py
PI = 3.14159

def area_circle(radius):
    return PI * radius ** 2

def area_square(side):
    return side ** 2

# main.py
import math_tools

print(math_tools.area_circle(5))
print(math_tools.area_square(4))
print(math_tools.PI)

That's it. Because math_tools.py sits in the same folder as the script you ran, import math_tools finds it. No configuration, no build step. Section 11 shows exactly where Python looks.

बस इतना ही। क्योंकि math_tools.py उसी folder में है जहाँ चलाई गई script है, import math_tools उसे ढूँढ लेता है। कोई configuration नहीं, कोई build step नहीं। Section 11 ठीक-ठीक दिखाता है कि Python कहाँ-कहाँ देखता है।

就这样。因为 math_tools.py 和你运行的脚本在同一个文件夹，import math_tools 就能找到它。不需要配置，也没有构建步骤。第 11 节会准确展示 Python 到哪些地方查找。

The Six Import Styles — Know All of Them 📥Import के छह तरीके — सब जानें 📥六种导入写法 — 全都要会 📥

# 1) Import the whole module - use it with a dot
import math
print(math.sqrt(16))

# 2) Import with an alias - handy for long names (numpy is installed with pip)
import numpy as np
print(np.array([1, 2, 3]) * 2)

# 3) Import specific names - no dot needed
from math import sqrt, pi
print(sqrt(16), pi)

# 4) Import a name with an alias
from datetime import date as dt
print(dt(2026, 1, 26).strftime("%d %b %Y"))

# 5) Import everything - avoid outside quick experiments
from math import *
print(floor(7.9))          # works, but where did floor come from?

# 6) Import from a module inside a package
from os.path import join
print(join("data", "file.csv"))

Style 2 uses numpy, a third-party package — install it first with python -m pip install numpy (Section 14). All the others are in the standard library.

तरीका 2 numpy इस्तेमाल करता है, जो third-party package है — पहले python -m pip install numpy से install करें (Section 14)। बाक़ी सब standard library में हैं।

写法 2 用到第三方包 numpy — 先用 python -m pip install numpy 安装（第 14 节）。其余都在标准库里。

Why from module import * Is Risky — Prooffrom module import * जोखिम भरा क्यों — सबूत为什么 from module import * 有风险 — 证明

def process(data):
    return [x.strip() for x in data]

def process(data):
    return sum(data)

from cleaning import *
from billing import *     # silently replaces process!

print(process.__module__)
print(process([" a ", " b "]))

The if __name__ == "__main__" Idiom 🚪if __name__ == "__main__" का मुहावरा 🚪if __name__ == "__main__" 惯用法 🚪

Every module has a variable called __name__. When you run a file directly, its __name__ is "__main__". When you import it, __name__ is the module's name. This one difference lets a file be both a script and a module. Here is one file, run in two different ways:

हर module में __name__ नाम का variable होता है। जब आप file को सीधे चलाते हैं, उसका __name__ "__main__" होता है। जब आप उसे import करते हैं, __name__ module का नाम होता है। यही एक फ़र्क़ file को script और module दोनों बनने देता है। यह एक file है, दो अलग तरीकों से चलाई गई:

每个模块都有一个名为 __name__ 的变量。直接 运行 文件时，它的 __name__ 是 "__main__"；被 导入 时，__name__ 是模块名。正是这一点区别，让一个文件既能当脚本 又能 当模块。下面是同一个文件的两种运行方式：

# math_tools.py
def area_circle(radius):
    return 3.14159 * radius ** 2

def demo():
    print("Testing area_circle:")
    print(area_circle(5))
    print(area_circle(10))

print("__name__ is", repr(__name__))

# This block ONLY runs when you execute the file directly
if __name__ == "__main__":
    demo()

import math_tools
print("main.py got", math_tools.area_circle(2))

Try It — __name__ Tracerकरके देखें — __name__ Tracer动手试试 — __name__ 跟踪器

Choose how the file is started, and whether it has the guard. Step through and watch which lines Python actually runs — the steps were recorded line by line with Python's tracer. Try no guard + imported to see the problem the guard solves.

चुनें कि file कैसे शुरू होती है, और उसमें guard है या नहीं। कदम-दर-कदम चलें और देखें Python असल में कौन-सी lines चलाता है — कदम Python के tracer से line-by-line दर्ज किए गए हैं। Guard किस समस्या को हल करता है, यह देखने के लिए no guard + imported आज़माएँ।

选择文件的启动方式，以及是否有守卫。逐步执行，看 Python 实际运行了哪些行 — 这些步骤是用 Python 跟踪器逐行记录的。试试 no guard + imported，看看守卫解决的是什么问题。

Imports Run Once — The Module Cache 🗄️Import एक ही बार चलता है — Module Cache 🗄️导入只运行一次 — 模块缓存 🗄️

The first import of a module runs its file and stores the module object in a dictionary called sys.modules. Every later import of the same name just looks it up there — the file is not run again.

किसी module का पहला import उसकी file चलाता है और module object को sys.modules नाम की dictionary में रख देता है। उसी नाम का हर अगला import बस वहाँ देखता है — file दोबारा नहीं चलती।

首次 import 某个模块时，会运行它的文件，并把模块对象存进名为 sys.modules 的字典。之后再导入同名模块，只是在那里查找 — 文件 不会 再次运行。

print("  ...loading noisy.py")
COUNT = 0

import sys
import importlib

import noisy
import noisy                 # second import: nothing printed
noisy.COUNT += 1

print("noisy" in sys.modules)
print(noisy.COUNT)

importlib.reload(noisy)      # force a fresh run of the file
print(noisy.COUNT)

Packages — Modules Grow Up 📦Packages — Modules बड़े होते हैं 📦包 — 模块长大了 📦

When one file grows into ten, group them in a folder — a package. Packages let you organise code by feature, share it between projects and publish libraries.

जब एक file दस बन जाए, तो उन्हें एक folder में रखें — एक package। Packages से आप code को feature के हिसाब से सजा सकते हैं, projects में साझा कर सकते हैं और libraries publish कर सकते हैं।

当一个文件长成十个，就把它们放进一个文件夹 — 包。包让你按功能组织代码、在项目间共享、发布库。

Importing from a Package — Dotted Paths 🔗Package से Import — Dots वाले Paths 🔗从包中导入 — 点号路径 🔗

Inside a package, import uses dots to walk down the folders: each dot goes one level deeper. This main.py sits next to the mypackage/ folder from the diagram above:

Package के अंदर import folders में नीचे जाने के लिए dots इस्तेमाल करता है: हर dot एक स्तर गहरा जाता है। यह main.py ऊपर के चित्र वाले mypackage/ folder के बगल में है:

在包里，import 用 点号 逐级进入文件夹：每个点深入一层。下面的 main.py 与上图的 mypackage/ 文件夹位于同一层：

# main.py - OUTSIDE the package
import mypackage.config
print(mypackage.config.DEBUG)

import mypackage.core.engine
print(mypackage.core.engine.run())

from mypackage.core import engine
print(engine.run())

from mypackage.core.engine import run
print(run())

from mypackage.core import engine as eng
print(eng.run())

The __init__.py File — What Goes in It? 🎁__init__.py File — इसमें क्या जाता है? 🎁__init__.py 文件 — 里面放什么？🎁

Most __init__.py files are empty. But __init__.py runs the first time the package is imported, so it is the perfect place to shape the package's public face: re-export the useful names and list them in __all__.

ज़्यादातर __init__.py files ख़ाली होती हैं। पर package के पहली बार import होने पर __init__.py चलती है, इसलिए यह package का सार्वजनिक चेहरा बनाने की बढ़िया जगह है: काम के नाम re-export करें और उन्हें __all__ में लिखें।

大多数 __init__.py 是空的。但包第一次被导入时 __init__.py 会运行，所以它是塑造包的 公开门面 的好地方：重新导出有用的名字，并在 __all__ 中列出它们。

# shop/__init__.py - the public face of the package
from .cart import add_item, total, _audit
from .config import VERSION

__all__ = ["add_item", "total", "VERSION"]

_items = []

def add_item(name, price):
    _items.append((name, price))

def total():
    return sum(price for _, price in _items)

def _audit():
    return list(_items)

from shop import add_item, total, VERSION     # short, thanks to __init__.py
add_item("pen", 20)
add_item("book", 150)
print("total:", total(), "| version:", VERSION)

from shop.cart import total as deep_total    # the long path still works
print(deep_total())

ns = {}
exec("from shop import *", ns)               # what does * bring in?
print(sorted(k for k in ns if not k.startswith("__")))

Absolute vs Relative Imports 🧭Absolute बनाम Relative Imports 🧭绝对导入与相对导入 🧭

When code inside a package imports another part of the same package, you can spell out the full path (absolute) or use dots relative to the current file (relative).

जब package के अंदर का code उसी package का दूसरा हिस्सा import करे, तो आप पूरा path लिख सकते हैं (absolute) या मौजूदा file के हिसाब से dots इस्तेमाल कर सकते हैं (relative)।

当包 内部 的代码导入 同一 包的其他部分时，你可以写出完整路径（绝对），也可以用相对当前文件的点号（相对）。

Here is engine.py using all three forms, started in two different ways:

यह engine.py तीनों रूप इस्तेमाल करती है, दो अलग तरीकों से शुरू की गई:

下面的 engine.py 用了全部三种写法，并以两种方式启动：

# mypackage/core/engine.py
from mypackage import config         # 1) absolute
from . import utils                  # 2) relative, same package (core/)
from .. import helpers               # 3) relative, parent package (mypackage/)

def run():
    return "engine running"

if __name__ == "__main__":
    print(config.VERSION, utils.tidy("  a   b  "), helpers.shout("go"))

Try It — Import Path Labकरके देखें — Import Path Lab动手试试 — 导入路径实验室

Choose who is importing, what it imports and which style it uses. Each of the 18 combinations was really run on these files — the console shows Python's actual result.

चुनें कौन import कर रहा है, क्या import करता है और कौन-सा तरीका इस्तेमाल करता है। 18 में से हर जोड़ इन files पर सच में चलाया गया — console Python का असली नतीजा दिखाता है।

选择谁在导入、导入什么、用哪种写法。18 种组合都在这些文件上真实运行过 — 控制台显示的是 Python 的实际结果。

How Python Finds a Module — The Search Path 🔎Python Module कैसे ढूँढता है — Search Path 🔎Python 如何找到模块 — 搜索路径 🔎

When you write import random, Python asks a fixed list of places, in order, and uses the first one that has it. The full order is:

जब आप import random लिखते हैं, Python जगहों की एक तय सूची से क्रम से पूछता है, और जिसके पास पहले मिले उसे इस्तेमाल करता है। पूरा क्रम यह है:

当你写 import random 时，Python 会 按顺序 询问一组固定的地方，用第一个找到的。完整顺序是：

Try It — Search Path Walkकरके देखें — Search Path Walk动手试试 — 搜索路径之旅

Pick a module, then add a local file with the same name, or a PYTHONPATH folder. Press Play and watch Python walk the list. Every result — including the real file path in the console — comes from actually running Python 3.13 in that situation. Compare random, math and os with a local file: only one of them gets hijacked!

एक module चुनें, फिर उसी नाम की local file, या PYTHONPATH folder जोड़ें। चलाएँ दबाएँ और Python को सूची में चलते देखें। हर नतीजा — console का असली file path भी — उस स्थिति में Python 3.13 को सच में चलाकर आया है। Local file के साथ random, math और os की तुलना करें: इनमें से सिर्फ़ एक ही hijack होता है!

选一个模块，再加上同名的本地文件或 PYTHONPATH 文件夹。点 播放，看 Python 沿列表查找。每个结果 — 包括控制台中的真实文件路径 — 都来自在该情境下实际运行 Python 3.13。比较一下带本地文件时的 random、math 和 os：只有一个会被劫持！

See Your Own Search Pathअपना Search Path देखें查看你自己的搜索路径

import sys
for path in sys.path:
    print(path)

These are the folders on the machine that built this page — yours will differ, but the shape is the same: your project first, then the standard library, then the folders where pip installs packages.

ये उस मशीन के folders हैं जिसने यह page बनाया — आपके अलग होंगे, पर ढाँचा वही है: पहले आपका project, फिर standard library, फिर वे folders जहाँ pip packages install करता है।

这些是构建本页面的机器上的文件夹 — 你的会不同，但结构一样：先是你的项目，然后是标准库，最后是 pip 安装包的文件夹。

The Shadowing Trap — ProofShadowing का जाल — सबूत遮蔽陷阱 — 证明

# random.py - oops, same name as the standard library module
print("my random.py was loaded!")

import random
print(random.randint(1, 6))

Practical Example — Building a Small Package 🛠️व्यावहारिक उदाहरण — एक छोटा Package बनाना 🛠️实战示例 — 构建一个小包 🛠️

A real, minimal package for text analysis: four files, one clean public API. The folder looks like this:

Text analysis के लिए एक असली, छोटा package: चार files, एक साफ़ public API। Folder ऐसा दिखता है:

一个真实的、精简的文本分析包：四个文件，一个干净的公开 API。文件夹结构如下：

textstats/
    __init__.py
    _internal.py
    counter.py
    reader.py
speech.txt
main.py

# Internal helpers - the leading underscore says "private"
import re

def _clean(text):
    """Remove punctuation, lowercase, collapse spaces."""
    text = re.sub(r"[^\w\s]", "", text.lower())
    return " ".join(text.split())

from collections import Counter

from ._internal import _clean       # relative import - same package

def word_count(text):
    """Total words in a piece of text."""
    return len(_clean(text).split())

def top_words(text, n=5):
    """The n most common words as (word, count) pairs."""
    return Counter(_clean(text).split()).most_common(n)

from pathlib import Path

def read_file(path):
    """Load the full text of a file."""
    return Path(path).read_text(encoding="utf-8")

# Expose the useful names at the package top level
from .counter import word_count, top_words
from .reader import read_file

__version__ = "1.0.0"
__all__ = ["word_count", "top_words", "read_file"]

import textstats

text = textstats.read_file("speech.txt")
print(textstats.word_count(text))
print(textstats.top_words(text, n=3))
print(textstats.__version__)

The Standard Library — Modules You Already Have 📚Standard Library — Modules जो आपके पास पहले से हैं 📚标准库 — 你已经拥有的模块 📚

Python ships with hundreds of modules — "batteries included". Python itself can tell you how many:

Python सैकड़ों modules के साथ आता है — "batteries included"। Python ख़ुद बता सकता है कितने:

Python 自带数百个模块 —"自带电池"。Python 自己就能告诉你有多少：

import sys

print(len(sys.stdlib_module_names), "standard library modules")
print("json" in sys.stdlib_module_names, "requests" in sys.stdlib_module_names)
print(sys.builtin_module_names[:6])

Third-Party Packages — pip, requirements.txt and venv 🌐Third-Party Packages — pip, requirements.txt और venv 🌐第三方包 — pip、requirements.txt 与 venv 🌐

Beyond the standard library, more than half a million projects live on PyPI, the Python Package Index. You install them with pip. Writing python -m pip (instead of plain pip) guarantees that pip installs into the same Python you are running.

Standard library के आगे, पाँच लाख से ज़्यादा projects PyPI (Python Package Index) पर हैं। आप इन्हें pip से install करते हैं। python -m pip लिखना (सिर्फ़ pip की जगह) पक्का करता है कि pip उसी Python में install करे जो आप चला रहे हैं।

在标准库之外，PyPI（Python 包索引）上有五十多万个项目，用 pip 安装。写 python -m pip（而不是单纯的 pip）可以确保 pip 安装到你正在运行的那个 Python 里。

# Install a package
$ python -m pip install requests

# Install an exact version
$ python -m pip install "pandas==2.2.3"

# Save the exact versions you use, then reinstall them anywhere
$ python -m pip freeze > requirements.txt
$ python -m pip install -r requirements.txt

# List or remove packages
$ python -m pip list
$ python -m pip uninstall requests

Virtual Environments — Essential for Real ProjectsVirtual Environments — असली Projects के लिए ज़रूरी虚拟环境 — 真实项目的必需品

# Create an isolated environment for THIS project only
$ python -m venv .venv

# Activate it (macOS / Linux)
$ source .venv/bin/activate

# Activate it (Windows, PowerShell or cmd)
> .venv\Scripts\activate

# Now pip installs ONLY into this project
(.venv) $ python -m pip install requests pandas

# Leave the environment
(.venv) $ deactivate

Common Pitfalls — and the Circular Import 🔄आम गड्ढे — और Circular Import 🔄常见陷阱 — 以及循环导入 🔄

A Circular Import, Step by Stepएक Circular Import, कदम-दर-कदम循环导入，一步一步看

# shop/users.py
from shop.orders import Order

class User:
    pass

# shop/orders.py
from shop.users import User        # <- circular!

class Order:
    pass

import shop.users

Try It — Circular Import Tracerकरके देखें — Circular Import Tracer动手试试 — 循环导入跟踪器

Step through the broken version and the fixed one. Each step was recorded by Python's tracer while really running these files. Watch the sys.modules panel: a module is added the moment it starts loading — that half-loaded entry is the whole problem.

टूटा हुआ और ठीक किया हुआ version, दोनों कदम-दर-कदम चलाएँ। हर कदम इन files को सच में चलाते समय Python के tracer से दर्ज हुआ। sys.modules panel देखें: module तभी जुड़ जाता है जब वह load होना शुरू होता है — यही आधी-load हुई entry पूरी समस्या है।

逐步查看出错版本和修复版本。每一步都是在真实运行这些文件时由 Python 跟踪器记录的。注意 sys.modules 面板：模块在 开始 加载的那一刻就被加入 — 这个"加载了一半"的条目正是问题所在。

The Fix — Move Shared Code into a Third Moduleइलाज — साझा Code को तीसरे Module में ले जाएँ修复 — 把共享代码移到第三个模块

# models.py - shared types live here
class User:
    def __init__(self, name):
        self.name = name

class Order:
    def __init__(self, user, item):
        self.user, self.item = user, item

# users.py
from models import User

def make_user(name):
    return User(name)

# orders.py
from models import Order
from users import make_user

def place(name, item):
    return Order(make_user(name), item)

from orders import place
o = place("Aarav", "notebook")
print(o.user.name, "ordered a", o.item)

Golden Rules and Quick Quiz 🏆सुनहरे नियम और छोटा Quiz 🏆黄金法则与小测验 🏆

Quick Quiz — 8 Questionsछोटा Quiz — 8 सवाल小测验 — 8 道题