把自己写的.py 文件做成全局可用的本地库

ytkz2026-01-232026-01-23

大家好，我是小白。今天这篇文章就来讲一讲如何把自己写的.py 文件做成全局可用的本地库。

一、核心原理：Python 模块搜索机制

在开始之前，先了解下 Python 的模块搜索规则：当你执行import module_name时，Python 会按以下顺序查找模块：

内置模块（如sys、os等）
sys.path列表中的目录（包括当前脚本目录、PYTHONPATH 环境变量指定目录、Python 安装目录下的 site-packages 等）
如果找不到，就会抛出ModuleNotFoundError

我们的目标就是把自己的模块所在路径添加到 Python 的搜索路径中，或者直接放到它本来就会搜索的目录里。

二、方案一：简单粗暴 —— 直接放入 site-packages（适合快速测试）

这是最直接的方法，适合临时测试或简单脚本的复用，原理就是把你的模块放到 Python 默认的第三方库目录里。

操作步骤：

找到 site-packages 目录
```
import numpy  # 任意第三方库均可
print(numpy.__file__)
```
输出类似C:\Users\用户名\AppData\Local\Programs\Python\Python39\lib\site-packages\numpy\__init__.py，其中...\site-packages\就是我们要找的目录。
放入模块
- 单个.py文件：直接复制到 site-packages 目录，即可用import 文件名导入
- 多个相关文件（包）：创建一个目录（如mytools），放入所有.py文件，并添加空的__init__.py文件（Python3.3 + 可省略，但建议保留以保证兼容性），再将整个目录复制到 site-packages

优点：无需额外配置，复制后立即生效，全局可用

缺点：与系统 Python 环境耦合，重装 Python 或切换环境会失效；容易与其他库冲突；不便于版本管理

适用场景：临时测试、简单工具脚本、不常更新的代码片段

三、方案二：灵活可控 —— 动态添加路径（适合开发调试）

这种方法在代码中动态修改sys.path，每次运行时添加模块路径，不影响系统环境，适合开发阶段频繁修改的模块。

操作步骤：

假设你的模块 / 包在D:\projects\my_python_libs\mypackage路径下：

# 在需要使用自定义模块的脚本开头添加
import sys
# 添加模块所在的父目录，而非模块目录本身
sys.path.append(r"D:\projects\my_python_libs")

# 现在可以直接导入
import mypackage
# 或从包中导入特定模块
from mypackage import utils

进阶技巧：自动获取模块路径（适合模块位置固定的情况）

import sys
import os
# 获取当前脚本所在目录
current_dir = os.path.dirname(os.path.abspath(__file__))
# 假设自定义模块在上级目录的my_libs文件夹
module_path = os.path.join(current_dir, "..", "my_libs")
# 规范化路径（处理../等相对路径）
module_path = os.path.normpath(module_path)
sys.path.append(module_path)

优点：不修改系统环境，灵活可控，适合开发调试；可在不同项目中使用不同版本的模块

缺点：每次使用都要添加代码；多人协作时需要统一路径；发布代码时可能需要额外处理

适用场景：开发阶段、频繁更新的模块、需要隔离环境的场景

四、方案三：一劳永逸 —— 设置 PYTHONPATH 环境变量（适合稳定工具）

这是方案二的 “永久版”，通过设置环境变量让 Python 启动时自动添加路径，效果与动态添加一致，但无需每次写代码配置，适合长期使用的稳定工具包。

Windows 系统设置：

按下Win+R，输入sysdm.cpl打开系统属性
切换到 “高级” 选项卡，点击 “环境变量”
在 “用户变量” 或 “系统变量” 中找到或新建PYTHONPATH
值设为你的模块所在父目录（如D:\projects\my_python_libs），多个路径用分号分隔
重启命令行或 IDE 使设置生效

macOS/Linux 系统设置：

打开终端，编辑 shell 配置文件（bash 用户为)
```
~/.bashrc
```
，zsh 用户为
```
~/.zshrc
```
```
nano ~/.bashrc
```

添加以下内容（路径替换为你的模块父目录）：

export PYTHONPATH="/Users/用户名/projects/my_python_libs:$PYTHONPATH"

使配置生效：
```
source ~/.bashrc
```

Conda 环境专属设置（推荐，避免污染全局环境）：

# 在激活环境后执行
conda env config vars set PYTHONPATH=/Users/用户名/projects/my_python_libs
# 重新激活环境使设置生效
conda activate 你的环境名

优点：一次设置，永久生效；全局可用；不影响系统 Python 环境；便于版本管理

缺点：需要重启终端 / IDE；多环境切换时可能需要重新配置；路径变更后需手动更新环境变量

适用场景：稳定工具包、长期使用的个人库、需要跨项目复用的核心模块

五、方案四：专业规范 —— 打包成正式库（适合长期维护 / 团队共享）

这是最推荐的方法，将代码打包成标准 Python 包，用pip安装到环境中，既规范又便于管理，还能发布到 PyPI 或私有仓库供团队使用。

完整步骤（基于 PEP621 标准，使用 pyproject.toml 而非老旧的 setup.py）：

创建规范的项目结构

mypackage_project/
├── src/                  # 源代码目录（推荐src布局，避免本地文件与安装包冲突）
│   └── mypackage/        # 你的包名
│       ├── __init__.py   # 包标识文件，可添加版本信息等
│       ├── module1.py    # 功能模块1
│       └── module2.py    # 功能模块2
├── tests/                # 测试目录（可选）
│   └── test_mypackage.py
├── pyproject.toml        # 包配置文件（核心）
└── README.md             # 说明文档（可选）

编写 pyproject.toml 配置文件

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mypackage"        # 包名，pip安装时使用
version = "0.1.0"         # 版本号
authors = [
  { name="Your Name", email="your.email@example.com" }
]
description = "我的Python工具库"
readme = "README.md"
requires-python = ">=3.8"  # 最低Python版本要求

安装构建工具并打包

# 安装构建工具
pip install --upgrade build
# 打包（生成dist目录，包含.whl和.tar.gz文件）
python -m build

安装到本地环境

# 安装打包好的库（-e表示可编辑模式，修改源码后无需重新安装）
pip install -e .
# 或安装dist目录下的wheel文件
pip install dist/mypackage-0.1.0-py3-none-any.whl

使用方法

安装完成后，在任何 Python 文件中都可直接导入：
```
import mypackage
from mypackage.module1 import my_function
```

优点：符合 Python 官方规范；支持版本管理；可通过 pip 安装卸载；适合团队协作；便于分发和更新；可与虚拟环境完美配合

缺点：配置步骤较多；初次使用有学习成本

适用场景：长期维护的项目；团队共享的工具；需要版本控制的模块；准备开源的代码

六、方案对比与选择建议

方案	难度	灵活性	环境隔离	适合场景
直接放入 site-packages	极易	低	差	临时测试、简单脚本
动态添加 sys.path	易	高	好	开发调试、频繁修改
设置 PYTHONPATH	中	中	中	稳定工具、个人常用库
打包成正式库	较高	高	极好	长期项目、团队协作