Python Pathlib：现代文件路径处理指南

Q: Python 中的 pathlib 是什么？

pathlib 是一个标准库模块（在 Python 3.4 中引入），提供用于处理文件系统路径的面向对象类。你可以创建 Path 对象并使用方法和运算符（如用于连接路径的 / 运算符），而不是将路径视为字符串。

Q: 什么时候应该使用 pathlib 而不是 os.path？

对于所有新的 Python 3.6+ 项目，使用 pathlib。它产生更简洁、更可读的代码并自动处理跨平台问题。仅在遗留 Python 2 代码或没有 pathlib 等效项的 os 函数（如 os.environ）中使用 os.path。

Q: pathlib 在 Windows 上工作吗？

是的。pathlib 在 Windows 上自动使用 WindowsPath，在 Linux/macOS 上使用 PosixPath。/ 运算符在所有平台上产生正确的路径。你在所有地方编写相同的代码。

Q: 我可以在 Pandas 中使用 Path 对象吗？

是的。自 Python 3.6 和 Pandas 0.21+ 起，你可以直接将 Path 对象传递给 pd.read_csv()、pd.read_excel()、df.to_csv() 和其他 I/O 函数，无需 str() 转换。

Q: Path.resolve() 和 Path.absolute() 有什么区别？

resolve() 返回绝对路径并解析符号链接和 ../. 组件。absolute() 返回绝对路径但不解析符号链接或规范化。在大多数情况下使用 resolve()。

Q: 如何在 Path 对象和字符串之间转换？

使用 str(path) 将 Path 转换为字符串，使用 Path(string) 从字符串创建 Path。大多数现代 Python 库直接接受 Path 对象，因此很少需要转换。

Name: Soren Atelier

Updated on 2026/2/13

如果你曾经写过这样的 Python 代码 os.path.join(os.path.dirname(os.path.abspath(__file__)), 'data', 'output')，你已经知道问题所在了。基于字符串的文件路径操作使用 os.path 冗长、难以阅读且容易出错。你拼接字符串却忘记分隔符。你硬编码 / 然后脚本在 Windows 上崩溃。你将五个 os.path 调用链式组合在一起只是为了获取文件的主名称，三个月后没人能读懂这段代码——包括你自己。

这些并非边缘情况。每个数据科学流程、每个 Web 应用、每个自动化脚本都会接触文件系统。在你的 Mac 上工作的路径在同事的 Windows 笔记本上却会失效。临时路径变量像技术债务一样在代码中累积。而且 os.path.join(os.path.dirname(...)) 调用嵌套得越多，你就越有可能引入只在生产环境中才会暴露的微妙 bug。

Python 的 pathlib 模块解决了这些问题。pathlib 在 Python 3.4 中引入，自 Python 3.6 起完全成熟，它用适当的 Path 对象替代了基于字符串的路径操作。路径使用 / 运算符连接。文件属性如 .name、.suffix 和 .stem 是属性而非函数调用。读写文件只需一行代码。而且在所有操作系统上都能完全一致地工作。本指南涵盖了 pathlib 的所有基本功能，从基础路径构建到数据科学工作流的高级模式。

📚

为什么使用 pathlib 而不是 os.path

在 pathlib 之前，Python 开发者依赖 os.path 进行路径操作，依赖 os 进行文件系统交互。这种方法虽然能用，但它将路径视为普通字符串。这带来了三个持续存在的问题：

可读性迅速下降。 比较 os.path.splitext(os.path.basename(filepath))[0] 和 Path(filepath).stem。两者都提取不带扩展名的文件名。一个是自解释的；另一个需要大脑解析。
跨平台 bug。 硬编码 / 作为分隔符或使用字符串拼接意味着你的 Linux 脚本在 Windows 上静默崩溃。os.path.join 有帮助，但即使忘记使用它一次也会埋下潜在的 bug。
功能分散。 要处理路径，你需要 os.path 进行分解，os 创建目录，glob 进行模式匹配，open() 进行文件 I/O。pathlib 将所有这些整合到一个 Path 对象中。

下面是同一个任务——在数据目录中查找所有 .csv 文件并读取第一个——的两种风格对比：

# os.path 方式
import os
import glob
 
data_dir = os.path.join(os.path.expanduser('~'), 'projects', 'data')
csv_files = glob.glob(os.path.join(data_dir, '**', '*.csv'), recursive=True)
if csv_files:
    with open(csv_files[0], 'r') as f:
        content = f.read()

# pathlib 方式
from pathlib import Path
 
data_dir = Path.home() / 'projects' / 'data'
csv_files = list(data_dir.rglob('*.csv'))
if csv_files:
    content = csv_files[0].read_text()

pathlib 版本更短、更易读，而且功能完全相同。除了 Path 之外不需要其他导入。没有字符串拼接。没有单独的 open() 调用。

创建 Path 对象

每个 pathlib 操作都从创建 Path 对象开始。Path 类在 Linux/macOS 上自动返回 PosixPath，在 Windows 上返回 WindowsPath。

from pathlib import Path
 
# 从字符串创建
p = Path('/home/user/documents/report.csv')
 
# 从多个片段创建（自动连接）
p = Path('home', 'user', 'documents', 'report.csv')
 
# 当前工作目录
cwd = Path.cwd()
print(cwd)  # 例如：/home/user/projects/myapp
 
# 用户主目录
home = Path.home()
print(home)  # 例如：/home/user
 
# 相对路径
p = Path('data/output/results.csv')
 
# 从现有路径创建
base = Path('/home/user')
full = Path(base, 'documents', 'file.txt')
print(full)  # /home/user/documents/file.txt

无参数的 Path() 返回 Path('.')，即当前目录的相对路径。当你需要绝对当前目录时，使用 Path.cwd()。

使用 / 运算符连接路径

pathlib 最独特的功能是重载的 / 运算符。你可以用 / 链式连接路径片段，而不是使用 os.path.join()：

from pathlib import Path
 
# 自然地构建路径
project = Path.home() / 'projects' / 'analysis'
data_file = project / 'data' / 'sales_2026.csv'
print(data_file)  # /home/user/projects/analysis/data/sales_2026.csv
 
# 混合 Path 对象和字符串
base = Path('/var/log')
app_log = base / 'myapp' / 'error.log'
print(app_log)  # /var/log/myapp/error.log
 
# 与变量结合
filename = 'report.pdf'
output = Path('output') / filename
print(output)  # output/report.pdf

/ 运算符自动处理分隔符。在 Windows 上，Path('C:/Users') / 'data' 会产生 C:\Users\data。你再也不需要考虑 / 与 \ 的区别了。

你也可以使用 joinpath() 获得相同的结果：

from pathlib import Path
 
# 等同于 Path('data') / 'raw' / 'file.csv'
p = Path('data').joinpath('raw', 'file.csv')
print(p)  # data/raw/file.csv

路径组件

每个 Path 对象都将其组件作为属性暴露。没有函数调用，没有字符串分割。

from pathlib import Path
 
p = Path('/home/user/projects/analysis/data/sales_report.final.csv')
 
print(p.name)       # sales_report.final.csv  （带扩展名的文件名）
print(p.stem)       # sales_report.final      （不带最后扩展名的文件名）
print(p.suffix)     # .csv                    （最后一个扩展名）
print(p.suffixes)   # ['.final', '.csv']      （所有扩展名）
print(p.parent)     # /home/user/projects/analysis/data
print(p.anchor)     # /                       （Unix 上的根目录，Windows 上的 C:\）
print(p.parts)      # ('/', 'home', 'user', 'projects', 'analysis', 'data', 'sales_report.final.csv')

导航父目录

.parent 属性返回直接父目录。链式调用可以访问更高层级：

from pathlib import Path
 
p = Path('/home/user/projects/analysis/data/output.csv')
 
print(p.parent)            # /home/user/projects/analysis/data
print(p.parent.parent)     # /home/user/projects/analysis
print(p.parent.parent.parent)  # /home/user/projects
 
# .parents 提供对所有祖先的索引访问
print(p.parents[0])  # /home/user/projects/analysis/data
print(p.parents[1])  # /home/user/projects/analysis
print(p.parents[2])  # /home/user/projects
print(p.parents[3])  # /home/user

修改路径组件

使用 .with_name()、.with_stem() 和 .with_suffix() 创建具有修改后组件的新路径：

from pathlib import Path
 
p = Path('/data/reports/sales_q1.csv')
 
# 完全更改文件名
print(p.with_name('revenue_q1.csv'))    # /data/reports/revenue_q1.csv
 
# 仅更改 stem（Python 3.9+）
print(p.with_stem('sales_q2'))          # /data/reports/sales_q2.csv
 
# 仅更改扩展名
print(p.with_suffix('.parquet'))        # /data/reports/sales_q1.parquet
 
# 移除扩展名
print(p.with_suffix(''))                # /data/reports/sales_q1
 
# 添加扩展名
backup = p.with_suffix(p.suffix + '.bak')
print(backup)                           # /data/reports/sales_q1.csv.bak

这些方法返回新的 Path 对象。它们不会在磁盘上重命名文件。

文件 I/O：读写操作

pathlib 消除了简单文件操作的 open() / with 样板代码：

from pathlib import Path
 
file_path = Path('example.txt')
 
# 写入文本（不存在则创建，存在则覆盖）
file_path.write_text('Hello, pathlib!\nSecond line.')
 
# 从文件读取文本
content = file_path.read_text()
print(content)
# Hello, pathlib!
# Second line.
 
# 写入字节
binary_path = Path('data.bin')
binary_path.write_bytes(b'\x00\x01\x02\x03')
 
# 读取字节
raw = binary_path.read_bytes()
print(raw)  # b'\x00\x01\x02\x03'

处理非 ASCII 文本时显式指定编码：

from pathlib import Path
 
# 写入 UTF-8 文本
Path('greeting.txt').write_text('こんにちは世界', encoding='utf-8')
 
# 使用编码读取
text = Path('greeting.txt').read_text(encoding='utf-8')
print(text)  # こんにちは世界

对于大文件或流式操作，使用 .open()，它返回与内置 open() 相同的文件句柄：

from pathlib import Path
 
log_file = Path('application.log')
 
# 逐行写入
with log_file.open('w') as f:
    for i in range(1000):
        f.write(f'Event {i}: processed\n')
 
# 逐行读取（对大文件内存友好）
with log_file.open('r') as f:
    for line in f:
        if 'error' in line.lower():
            print(line.strip())

目录操作

创建目录

from pathlib import Path
 
# 创建单个目录
Path('output').mkdir()
 
# 连同父目录一起创建（类似 os.makedirs）
Path('data/raw/2026/february').mkdir(parents=True, exist_ok=True)
 
# parents=True 创建所有缺失的父目录
# exist_ok=True 如果目录已存在则防止报错

一个常见错误是忘记 parents=True。没有它，如果任何父目录缺失，mkdir() 会抛出 FileNotFoundError。创建嵌套目录时始终使用 parents=True，使用 exist_ok=True 使操作幂等。

列出目录内容

from pathlib import Path
 
project = Path('.')
 
# 列出所有条目（文件和目录）
for entry in project.iterdir():
    print(entry.name, '(dir)' if entry.is_dir() else '(file)')
 
# 仅筛选文件
files = [f for f in project.iterdir() if f.is_file()]
print(f"Found {len(files)} files")
 
# 仅筛选目录
dirs = [d for d in project.iterdir() if d.is_dir()]
print(f"Found {len(dirs)} directories")
 
# 按名称排序
for entry in sorted(project.iterdir()):
    print(entry.name)

删除目录和文件

from pathlib import Path
 
# 删除文件
Path('temp_output.csv').unlink()
 
# 仅当文件存在时删除（Python 3.8+）
Path('temp_output.csv').unlink(missing_ok=True)
 
# 删除空目录
Path('empty_dir').rmdir()

rmdir() 只能删除空目录。对于非空目录，使用 shutil.rmtree()：

from pathlib import Path
import shutil
 
target = Path('data/old_output')
if target.exists():
    shutil.rmtree(target)

Glob 模式：查找文件

pathlib 内置了 glob 支持。无需单独导入 glob 模块。

基本 Glob

from pathlib import Path
 
project = Path('/home/user/project')
 
# 查找目录中的所有 Python 文件
for py_file in project.glob('*.py'):
    print(py_file.name)
 
# 查找所有 CSV 文件
csv_files = list(project.glob('*.csv'))
print(f"Found {len(csv_files)} CSV files")
 
# 查找匹配模式的文件
reports = list(project.glob('report_*.xlsx'))

使用 rglob 进行递归 Glob

rglob() 递归搜索所有子目录。它等同于 glob('**/*.pattern) 但更便利：

from pathlib import Path
 
project = Path('/home/user/project')
 
# 在所有子目录中查找所有 Python 文件
all_py = list(project.rglob('*.py'))
print(f"Found {len(all_py)} Python files across all directories")
 
# 递归查找所有 Jupyter notebooks
notebooks = list(project.rglob('*.ipynb'))
for nb in notebooks:
    print(f"  {nb.relative_to(project)}")
 
# 查找所有图像文件
images = list(project.rglob('*.png')) + list(project.rglob('*.jpg'))
 
# 查找所有文件（无筛选）
all_files = [f for f in project.rglob('*') if f.is_file()]

高级 Glob 模式

from pathlib import Path
 
data = Path('data')
 
# 单字符通配符
data.glob('file_?.csv')        # file_1.csv, file_a.csv
 
# 字符范围
data.glob('report_202[456].csv')  # report_2024.csv, report_2025.csv, report_2026.csv
 
# 任意子目录层级
data.glob('**/output/*.csv')   # data/raw/output/result.csv, data/processed/output/result.csv
 
# 多个扩展名（组合两个 globs）
from itertools import chain
all_data = chain(data.rglob('*.csv'), data.rglob('*.parquet'))

检查路径

pathlib 提供了清晰的布尔方法用于检查路径状态：

from pathlib import Path
 
p = Path('/home/user/projects/data.csv')
 
# 路径是否存在？
print(p.exists())       # True 或 False
 
# 是否是文件？
print(p.is_file())      # 如果存在且是普通文件则为 True
 
# 是否是目录？
print(p.is_dir())       # 如果存在且是目录则为 True
 
# 是否是符号链接？
print(p.is_symlink())   # 如果存在且是符号链接则为 True
 
# 是否是绝对路径？
print(p.is_absolute())  # True （/home/... 以根目录开头）
print(Path('data.csv').is_absolute())  # False （相对路径）

这些方法对于不存在的路径从不抛出异常。它们只是返回 False，这使得它们在条件语句中安全使用：

from pathlib import Path
 
config = Path('config.yaml')
if config.is_file():
    settings = config.read_text()
else:
    print("Config file not found, using defaults")

路径操作

解析和规范化路径

from pathlib import Path
 
# 解析为绝对路径（同时解析符号链接）
p = Path('data/../data/./output.csv')
print(p.resolve())  # /home/user/project/data/output.csv
 
# 获取绝对路径但不解析符号链接
print(p.absolute())  # /home/user/project/data/../data/./output.csv
 
# 展开用户主目录
p = Path('~/Documents/report.csv')
print(p.expanduser())  # /home/user/Documents/report.csv

相对路径

from pathlib import Path
 
full_path = Path('/home/user/projects/analysis/data/output.csv')
base = Path('/home/user/projects')
 
# 获取从 base 到 full_path 的相对路径
relative = full_path.relative_to(base)
print(relative)  # analysis/data/output.csv
 
# 如果路径不是相对于 base 的，这会抛出 ValueError
try:
    Path('/var/log/app.log').relative_to(base)
except ValueError as e:
    print(e)  # '/var/log/app.log' is not relative to '/home/user/projects'
 
# Python 3.12+：is_relative_to() 检查
print(full_path.is_relative_to(base))   # True
print(Path('/var/log').is_relative_to(base))  # False

文件元数据和状态

from pathlib import Path
from datetime import datetime
 
p = Path('data.csv')
 
# 获取文件状态
stat = p.stat()
print(f"Size: {stat.st_size} bytes")
print(f"Modified: {datetime.fromtimestamp(stat.st_mtime)}")
print(f"Created: {datetime.fromtimestamp(stat.st_ctime)}")
 
# 便捷方法：直接获取大小（通过 stat）
size_mb = p.stat().st_size / (1024 * 1024)
print(f"Size: {size_mb:.2f} MB")
 
# 检查两个路径是否指向同一文件
p1 = Path('/home/user/data.csv')
p2 = Path.home() / 'data.csv'
print(p1.samefile(p2))  # True （如果它们解析到同一文件）

重命名和移动文件

from pathlib import Path
 
# 重命名文件（返回新的 Path）
old = Path('report_draft.csv')
new = old.rename('report_final.csv')
print(new)  # report_final.csv
 
# 移动到不同目录
source = Path('output/temp_results.csv')
dest = source.rename(Path('archive') / source.name)
 
# 替换文件（如果目标存在则覆盖）
Path('new_data.csv').replace('data.csv')

注意：.rename() 在 Unix 上会覆盖目标文件，但在 Windows 上可能会报错。使用 .replace() 可以保证跨平台的覆盖行为。

os.path vs pathlib：完整对比

这里是一个参考表，将常见的 os.path 操作映射到其 pathlib 等价物：

操作	os.path / os	pathlib
连接路径	`os.path.join('a', 'b')`	`Path('a') / 'b'`
当前目录	`os.getcwd()`	`Path.cwd()`
主目录	`os.path.expanduser('~')`	`Path.home()`
绝对路径	`os.path.abspath(p)`	`Path(p).resolve()`
文件名	`os.path.basename(p)`	`Path(p).name`
目录	`os.path.dirname(p)`	`Path(p).parent`
扩展名	`os.path.splitext(p)[1]`	`Path(p).suffix`
Stem（不带扩展名的名称）	`os.path.splitext(os.path.basename(p))[0]`	`Path(p).stem`
是否存在	`os.path.exists(p)`	`Path(p).exists()`
是否是文件	`os.path.isfile(p)`	`Path(p).is_file()`
是否是目录	`os.path.isdir(p)`	`Path(p).is_dir()`
是否是符号链接	`os.path.islink(p)`	`Path(p).is_symlink()`
是否是绝对路径	`os.path.isabs(p)`	`Path(p).is_absolute()`
文件大小	`os.path.getsize(p)`	`Path(p).stat().st_size`
列出目录	`os.listdir(p)`	`Path(p).iterdir()`
创建目录	`os.makedirs(p, exist_ok=True)`	`Path(p).mkdir(parents=True, exist_ok=True)`
删除文件	`os.remove(p)`	`Path(p).unlink()`
删除目录	`os.rmdir(p)`	`Path(p).rmdir()`
重命名	`os.rename(old, new)`	`Path(old).rename(new)`
读取文件	`open(p).read()`	`Path(p).read_text()`
写入文件	`open(p, 'w').write(text)`	`Path(p).write_text(text)`
Glob	`glob.glob('*.py')`	`Path('.').glob('*.py')`
递归 Glob	`glob.glob('*/.py', recursive=True)`	`Path('.').rglob('*.py')`
展开用户目录	`os.path.expanduser(p)`	`Path(p).expanduser()`
相对路径	`os.path.relpath(p, base)`	`Path(p).relative_to(base)`

使用临时文件

pathlib 与 Python 的 tempfile 模块完美集成：

from pathlib import Path
import tempfile
 
# 将临时目录创建为 Path
with tempfile.TemporaryDirectory() as tmp_dir:
    tmp_path = Path(tmp_dir)
 
    # 使用 pathlib 写入临时文件
    data_file = tmp_path / 'intermediate_results.csv'
    data_file.write_text('col1,col2\n1,2\n3,4\n')
 
    config_file = tmp_path / 'run_config.json'
    config_file.write_text('{"epochs": 100, "lr": 0.001}')
 
    # 列出我们创建的内容
    for f in tmp_path.iterdir():
        print(f"{f.name}: {f.stat().st_size} bytes")
 
    # 处理文件...
    print(data_file.read_text())
 
# 目录和所有文件在此处自动删除

from pathlib import Path
import tempfile
 
# 创建命名临时文件
tmp = tempfile.NamedTemporaryFile(suffix='.csv', delete=False)
tmp_path = Path(tmp.name)
tmp.close()
 
# 使用 pathlib 写入
tmp_path.write_text('id,value\n1,100\n2,200\n')
print(f"Temp file at: {tmp_path}")
 
# 完成后清理
tmp_path.unlink()

数据科学工作流中的 Pathlib

数据科学项目通常涉及从多个目录读取数据集、为结果创建输出文件夹以及管理实验产物。pathlib 使这些模式变得简洁可靠。

组织项目目录

from pathlib import Path
 
def setup_experiment(experiment_name):
    """创建标准的实验目录结构。"""
    base = Path('experiments') / experiment_name
 
    dirs = ['data/raw', 'data/processed', 'models', 'results/figures', 'results/tables', 'logs']
 
    for d in dirs:
        (base / d).mkdir(parents=True, exist_ok=True)
 
    # 创建配置文件
    config = base / 'config.json'
    if not config.exists():
        config.write_text('{"learning_rate": 0.001, "epochs": 50}')
 
    print(f"Experiment directory ready: {base.resolve()}")
    return base
 
project = setup_experiment('sales_forecast_v2')

读取多个数据文件

from pathlib import Path
import pandas as pd
 
data_dir = Path('data/raw')
 
# 将所有 CSV 文件读入单个 DataFrame
dfs = []
for csv_file in sorted(data_dir.glob('*.csv')):
    print(f"Loading {csv_file.name}...")
    df = pd.read_csv(csv_file)
    df['source_file'] = csv_file.stem  # 添加源文件名
    dfs.append(df)
 
combined = pd.concat(dfs, ignore_index=True)
print(f"Loaded {len(combined)} rows from {len(dfs)} files")
 
# 保存到 processed 目录
output_path = Path('data/processed') / 'combined_sales.parquet'
output_path.parent.mkdir(parents=True, exist_ok=True)
combined.to_parquet(output_path)

使用 pathlib 加载 CSV 数据后，你可以使用 PyGWalker (opens in a new tab) 进行可视化探索。它将任何 Pandas DataFrame 转换为类似 Tableau 的交互式界面，支持拖放式数据探索——无需额外代码。

保存实验结果

from pathlib import Path
from datetime import datetime
import json
 
def save_results(metrics, experiment_dir):
    """使用时间戳保存实验指标。"""
    results_dir = Path(experiment_dir) / 'results'
    results_dir.mkdir(parents=True, exist_ok=True)
 
    timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
    output_file = results_dir / f'metrics_{timestamp}.json'
 
    output_file.write_text(json.dumps(metrics, indent=2))
    print(f"Results saved to {output_file}")
    return output_file
 
# 使用
metrics = {'accuracy': 0.94, 'f1_score': 0.91, 'loss': 0.187}
save_results(metrics, 'experiments/sales_forecast_v2')

在 Notebook 中管理文件路径

在 Jupyter notebooks 中工作时，路径经常出问题，因为 notebook 的工作目录可能与项目根目录不同。pathlib 使这很容易处理：

from pathlib import Path
 
# 始终从 notebook 位置解析为绝对路径
NOTEBOOK_DIR = Path.cwd()
PROJECT_ROOT = NOTEBOOK_DIR.parent  # 如果 notebook 在 notebooks/ 中
DATA_DIR = PROJECT_ROOT / 'data'
OUTPUT_DIR = PROJECT_ROOT / 'output'
 
# 现在所有路径都是绝对且可靠的
train_data = DATA_DIR / 'train.csv'
print(f"Loading: {train_data}")
assert train_data.exists(), f"Missing: {train_data}"

如果你在 Jupyter 中大量工作，并想要一个帮助管理项目文件和数据路径的 AI 驱动环境，RunCell (opens in a new tab) 为你的 notebook 添加了一层 AI 代理。描述你的需求——"查找 data 目录中的所有 Parquet 文件并加载最新的一个"——它就会生成 pathlib 代码并为你运行。

常见模式和技巧

使用原子替换进行安全文件写入

通过首先写入临时文件，然后原子替换目标文件来防止数据损坏：

from pathlib import Path
import tempfile
 
def safe_write(target_path, content):
    """原子写入内容到文件以防止损坏。"""
    target = Path(target_path)
    target.parent.mkdir(parents=True, exist_ok=True)
 
    # 在同一目录写入临时文件
    tmp = tempfile.NamedTemporaryFile(
        mode='w', dir=target.parent, suffix='.tmp', delete=False
    )
    tmp_path = Path(tmp.name)
    try:
        tmp.write(content)
        tmp.close()
        tmp_path.replace(target)  # 在大多数文件系统上是原子的
    except Exception:
        tmp_path.unlink(missing_ok=True)
        raise
 
safe_write('config/settings.json', '{"debug": true}')

批量重命名文件

from pathlib import Path
 
photos_dir = Path('photos')
 
# 将所有 .jpeg 文件重命名为 .jpg
for f in photos_dir.glob('*.jpeg'):
    f.rename(f.with_suffix('.jpg'))
 
# 为所有文件添加前缀
for i, f in enumerate(sorted(photos_dir.glob('*.jpg')), start=1):
    new_name = f.parent / f'photo_{i:04d}{f.suffix}'
    f.rename(new_name)

按大小查找重复文件

from pathlib import Path
from collections import defaultdict
 
def find_potential_duplicates(directory):
    """查找大小相同的文件（潜在的重复文件）。"""
    size_map = defaultdict(list)
 
    for f in Path(directory).rglob('*'):
        if f.is_file():
            size_map[f.stat().st_size].append(f)
 
    # 仅返回包含多个文件的组
    return {size: files for size, files in size_map.items() if len(files) > 1}
 
dupes = find_potential_duplicates('data')
for size, files in dupes.items():
    print(f"\n{size} bytes:")
    for f in files:
        print(f"  {f}")

构建文件树可视化

from pathlib import Path
 
def tree(directory, prefix='', max_depth=3, _depth=0):
    """打印目录的树形结构。"""
    if _depth >= max_depth:
        return
 
    path = Path(directory)
    entries = sorted(path.iterdir(), key=lambda e: (e.is_file(), e.name))
 
    for i, entry in enumerate(entries):
        is_last = (i == len(entries) - 1)
        connector = '└── ' if is_last else '├── '
        print(f'{prefix}{connector}{entry.name}')
 
        if entry.is_dir():
            extension = '    ' if is_last else '│   '
            tree(entry, prefix + extension, max_depth, _depth + 1)
 
tree('my_project', max_depth=3)

输出：

├── data
│   ├── processed
│   │   └── combined.csv
│   └── raw
│       ├── sales_2025.csv
│       └── sales_2026.csv
├── notebooks
│   └── analysis.ipynb
├── output
│   └── figures
└── requirements.txt

常见错误及如何避免

错误 1：将字符串与 Path 对象比较

from pathlib import Path
 
p = Path('data/output.csv')
 
# 错误：将字符串与 Path 比较
if p == 'data/output.csv':  # 可能能用但脆弱
    print("Match")
 
# 正确：Path 与 Path 比较，或使用 str()
if p == Path('data/output.csv'):
    print("Match")
 
# 正确：如果需要则转换为字符串
if str(p) == 'data/output.csv':
    print("Match")

错误 2：在 mkdir 中忘记 parents=True

from pathlib import Path
 
# 错误：如果 'data' 不存在会抛出 FileNotFoundError
# Path('data/raw/2026').mkdir()
 
# 正确：创建所有缺失的父目录
Path('data/raw/2026').mkdir(parents=True, exist_ok=True)

错误 3：使用字符串拼接而不是 /

from pathlib import Path
 
base = Path('/home/user')
 
# 错误：字符串拼接会破坏 pathlib
# bad = base + '/data/file.csv'  # TypeError
 
# 正确：使用 / 运算符
good = base / 'data' / 'file.csv'

错误 4：将 Path 传递给需要字符串的库

大多数现代库（Pandas、NumPy、PIL 等）原生接受 Path 对象。但如果你遇到需要字符串的旧库，显式转换：

from pathlib import Path
 
p = Path('data/output.csv')
 
# 大多数库直接接受 Path
import pandas as pd
df = pd.read_csv(p)  # 正常工作
 
# 对于需要字符串的旧库
import some_legacy_lib
some_legacy_lib.process(str(p))  # 用 str() 转换
 
# os.fspath() 也能工作（Python 3.6+）
import os
some_legacy_lib.process(os.fspath(p))

错误 5：使用硬编码路径

from pathlib import Path
 
# 错误：硬编码绝对路径
# data_path = Path('/home/alice/project/data/sales.csv')
 
# 正确：从相对或动态组件构建
data_path = Path.cwd() / 'data' / 'sales.csv'
 
# 正确：从主目录构建
config_path = Path.home() / '.config' / 'myapp' / 'settings.json'
 
# 正确：从环境变量构建
import os
data_root = Path(os.getenv('DATA_DIR', 'data'))
data_path = data_root / 'sales.csv'

常见问题

Python 中的 pathlib 是什么？

pathlib 是一个标准库模块（在 Python 3.4 中引入），提供用于处理文件系统路径的面向对象类。你可以创建 Path 对象并使用方法和运算符，而不是将路径视为字符串并使用 os.path.join() 等函数。它自动处理跨平台路径差异。

什么时候应该使用 pathlib 而不是 os.path？

对于所有新的 Python 3.6+ 项目，使用 pathlib。它产生更简洁、更可读的代码，将路径操作整合到单个对象中，并自动处理跨平台问题。使用 os.path 的唯一理由是维护必须支持 Python 2 的遗留代码，或使用少数没有 pathlib 等效项的 os 函数（如用于环境变量的 os.environ）。

pathlib 在 Windows 上工作吗？

是的。pathlib 在 Windows 上自动使用 WindowsPath 对象，在 Linux/macOS 上使用 PosixPath。/ 运算符在 Windows 上产生反斜杠分隔的路径。你在所有平台上编写相同的代码，pathlib 处理差异。

我可以在 Pandas 中使用 Path 对象吗？

是的。自 Python 3.6 和 Pandas 0.21+ 起，你可以直接将 Path 对象传递给 pd.read_csv()、pd.read_excel()、df.to_csv() 和其他 I/O 函数。不需要 str() 转换。

Path.resolve() 和 Path.absolute() 有什么区别？

.resolve() 返回绝对路径并解析任何符号链接和 ../. 组件。.absolute() 返回绝对路径但不解析符号链接或规范化路径。在大多数情况下，.resolve() 是你想要的。

如何在 Path 对象和字符串之间转换？

使用 str(path) 将 Path 转换为字符串。使用 Path(string) 从字符串创建 Path。你也可以使用 os.fspath(path) 进行显式字符串转换。大多数现代 Python 库直接接受 Path 对象，因此很少需要转换。

结论

Python 的 pathlib 模块是现代文件路径操作的标准。/ 运算符使路径连接可读。.name、.stem、.suffix 和 .parent 等属性消除了冗长的 os.path 函数链。用于读取、写入、创建目录和 glob 的内置方法将过去需要 os、os.path、glob 和 open() 的功能整合到一个一致的 API 中。

从 os.path 到 pathlib 的迁移很简单：用 / 替换 os.path.join()，用 .exists() 替换 os.path.exists()，用 .mkdir(parents=True) 替换 os.makedirs()，用 .glob() 或 .rglob() 替换 glob.glob()。每个主要的 Python 库——Pandas、NumPy、PIL、PyTorch——现在都原生接受 Path 对象。在新项目中没有理由避免使用它。

从小处开始。选择一个包含混乱 os.path 代码的脚本。用 pathlib 替换路径操作。代码会变得更短、更可读、更可移植。然后对下一个脚本做同样的事。

📚