Python实用工具：s3fs 高效操作AWS S3存储的完整指南

一、s3fs 库核心介绍

s3fs 是一款为 Python 开发者提供便捷访问AWS S3对象存储的文件系统接口库，它基于 fsspec 框架实现，能够将 S3 存储桶映射为本地可操作的文件系统，支持常规的文件读写、目录遍历等操作。其工作原理是通过对接 AWS 的 boto3 客户端，将 S3 的对象存储操作转化为类 POSIX 的文件系统调用，让开发者无需关注 S3 API 的细节即可操作云端存储。

该库的优点是语法简洁、与 Python 内置 io 模块兼容、支持分块读写大文件；缺点是依赖 boto3 配置，且大规模并发操作时需手动优化性能。s3fs 采用 BSD-3-Clause 开源许可证，允许商业和非商业自由使用、修改和分发。

二、s3fs 安装与环境配置

2.1 安装方式

s3fs 的安装非常简单，推荐使用 pip 包管理工具进行安装，在命令行中执行以下命令即可完成安装：

pip install s3fs

如果需要安装特定版本的 s3fs，可以指定版本号，例如安装 2023.10.0 版本：

pip install s3fs==2023.10.0

安装完成后，可以在 Python 环境中通过导入语句验证是否安装成功：

import s3fs
print(s3fs.__version__)

运行上述代码，如果控制台输出对应的版本号，说明安装成功。

2.2 环境配置

s3fs 操作 AWS S3 依赖于 AWS 的身份认证，主要有以下三种配置方式，开发者可以根据实际场景选择：

1. 配置文件认证
   在本地创建 AWS 配置文件，通常位于 ~/.aws/credentials（Linux/Mac）或 C:\Users\用户名\.aws\credentials（Windows）路径下，文件内容格式如下： [default] aws_access_key_id = 你的Access Key ID aws_secret_access_key = 你的Secret Access Key region = 你的S3存储桶所在区域，例如us-east-1 配置完成后，s3fs 会自动读取该文件的认证信息，无需在代码中手动传入密钥。
2. 环境变量认证
   在系统环境变量中设置 AWS 认证信息，适用于服务器或容器化部署场景，需要设置的环境变量如下： # Linux/Mac 系统设置方式 export AWS_ACCESS_KEY_ID=你的Access Key ID export AWS_SECRET_ACCESS_KEY=你的Secret Access Key export AWS_REGION=你的S3存储桶所在区域 Windows 系统可以通过“系统属性-高级-环境变量”界面添加上述变量。
3. 代码中手动传入认证信息
   如果不希望配置本地文件或环境变量，可以在代码中直接传入 AWS 密钥和区域信息，示例如下：
   python import s3fs # 手动配置认证信息 fs = s3fs.S3FileSystem( key='你的Access Key ID', secret='你的Secret Access Key', client_kwargs={'region_name': 'us-east-1'} )
   注意：这种方式会将密钥硬编码在代码中，存在安全风险，生产环境不推荐使用。

三、s3fs 核心功能与代码实例

s3fs 的核心功能是模拟本地文件系统操作 S3 存储桶，其 API 设计与 Python 内置的 os 模块高度相似，降低了开发者的学习成本。下面将详细介绍 s3fs 的常用功能，并提供可直接运行的代码实例。

3.1 连接 S3 存储桶并遍历文件

使用 s3fs 首先需要创建 S3FileSystem 实例，该实例是操作 S3 的核心对象。创建实例后，可以通过 ls 方法遍历存储桶中的文件和目录。

import s3fs
# 创建 S3FileSystem 实例，默认读取本地配置文件的认证信息
fs = s3fs.S3FileSystem()
# 遍历指定存储桶中的内容，格式为 bucket_name/path
bucket_path = 'my-s3-bucket/test-folder'
# 列出存储桶路径下的所有文件和目录
file_list = fs.ls(bucket_path)
print(f"存储桶 {bucket_path} 下的内容：")
for file in file_list:
    print(file)

代码说明：

• s3fs.S3FileSystem() 会自动加载本地 AWS 配置文件或环境变量中的认证信息。
• fs.ls() 方法的参数是 S3 存储桶的路径，格式为 存储桶名称/目录路径，如果直接传入存储桶名称，则会列出存储桶根目录的内容。
• 运行代码前，需要将 my-s3-bucket/test-folder 替换为实际的 S3 存储桶和目录路径。

3.2 文件的上传与下载

文件的上传和下载是操作 S3 最常用的功能，s3fs 提供了 put（本地文件上传到 S3）和 get（S3 文件下载到本地）两个方法，同时支持分块传输大文件。

3.2.1 本地文件上传到 S3

import s3fs
# 创建 S3FileSystem 实例
fs = s3fs.S3FileSystem()
# 本地文件路径
local_file_path = './local_test.txt'
# S3 目标路径，格式为 bucket_name/remote_file_name
s3_target_path = 'my-s3-bucket/uploaded_test.txt'
# 上传本地文件到 S3
fs.put(local_file_path, s3_target_path)
print(f"成功将 {local_file_path} 上传到 {s3_target_path}")

代码说明：

• fs.put(local_path, remote_path) 方法接收两个参数，分别是本地文件路径和 S3 目标路径。
• 如果 S3 目标路径中的目录不存在，s3fs 会自动创建对应的目录结构。

3.2.2 S3 文件下载到本地

import s3fs
fs = s3fs.S3FileSystem()
# S3 源文件路径
s3_source_path = 'my-s3-bucket/uploaded_test.txt'
# 本地目标路径
local_target_path = './downloaded_test.txt'
# 从 S3 下载文件到本地
fs.get(s3_source_path, local_target_path)
print(f"成功将 {s3_source_path} 下载到 {local_target_path}")

代码说明：

• fs.get(remote_path, local_path) 方法接收两个参数，分别是 S3 源文件路径和本地目标路径。
• 如果本地目标路径的目录不存在，需要提前创建，否则会抛出文件不存在的异常。

3.2.3 大文件的分块上传与下载

当文件大小超过 100MB 时，推荐使用分块传输的方式，避免因网络问题导致传输失败。s3fs 支持通过 block_size 参数设置分块大小，默认分块大小为 5MB。

import s3fs
# 创建 S3FileSystem 实例，设置分块大小为 10MB
fs = s3fs.S3FileSystem(block_size=10*1024*1024)
# 大文件上传
large_local_file = './large_file.zip'
large_s3_path = 'my-s3-bucket/large_file.zip'
fs.put(large_local_file, large_s3_path)
print("大文件上传完成")
# 大文件下载
fs.get(large_s3_path, './downloaded_large_file.zip')
print("大文件下载完成")

代码说明：

• block_size 参数的单位是字节，10*1024*1024 表示 10MB。
• 分块传输时，s3fs 会将大文件拆分为多个小块，逐个传输，传输失败的块会自动重试。

3.3 文件的读写操作

s3fs 支持直接读写 S3 中的文件，无需先下载到本地，这一功能对于处理云端文件非常高效。其读写 API 与 Python 内置的 open 函数类似。

3.3.1 读取 S3 中的文本文件

import s3fs
fs = s3fs.S3FileSystem()
# S3 文本文件路径
s3_text_file = 'my-s3-bucket/test.txt'
# 以只读模式打开 S3 中的文本文件
with fs.open(s3_text_file, 'r', encoding='utf-8') as f:
    content = f.read()
    print("S3 文本文件内容：")
    print(content)

代码说明：

• fs.open() 方法的参数与 Python 内置 open 函数类似，'r' 表示只读模式，encoding='utf-8' 指定文件编码。
• 使用 with 语句可以自动关闭文件句柄，避免资源泄漏。

3.3.2 向 S3 写入文本文件

import s3fs
fs = s3fs.S3FileSystem()
# S3 目标文本文件路径
s3_write_file = 'my-s3-bucket/write_test.txt'
# 以写入模式打开文件，如果文件不存在则创建，存在则覆盖
with fs.open(s3_write_file, 'w', encoding='utf-8') as f:
    f.write("这是通过 s3fs 写入 S3 的文本内容\n")
    f.write("第二行文本内容")
print(f"成功向 {s3_write_file} 写入内容")

代码说明：

• 'w' 模式表示写入模式，如果 S3 中已存在同名文件，会被覆盖。
• 如果需要追加内容，可以使用 'a' 模式，示例如下：

with fs.open(s3_write_file, 'a', encoding='utf-8') as f:
    f.write("\n这是追加的文本内容")

3.3.3 读写二进制文件

对于图片、视频、压缩包等二进制文件，需要使用 'rb'（只读二进制）和 'wb'（写入二进制）模式。

import s3fs
fs = s3fs.S3FileSystem()
# 读取二进制文件（如图片）
s3_image_path = 'my-s3-bucket/test_image.png'
with fs.open(s3_image_path, 'rb') as f:
    image_data = f.read()
    print(f"读取到的图片数据大小：{len(image_data)} 字节")
# 写入二进制文件
local_image_path = './local_image.png'
s3_target_image = 'my-s3-bucket/uploaded_image.png'
with open(local_image_path, 'rb') as local_f, fs.open(s3_target_image, 'wb') as s3_f:
    s3_f.write(local_f.read())
print("二进制图片文件上传完成")

代码说明：

• 读写二进制文件时，不需要指定 encoding 参数。
• 上述代码通过嵌套 with 语句，实现了本地二进制文件到 S3 的直接上传。

3.4 目录的创建与删除

s3fs 支持对 S3 中的目录进行创建、删除等操作，对应的方法分别是 mkdir 和 rm。

3.4.1 创建目录

import s3fs
fs = s3fs.S3FileSystem()
# 要创建的 S3 目录路径
new_dir_path = 'my-s3-bucket/new-folder/sub-folder'
# 创建目录，parents=True 表示如果父目录不存在则自动创建
fs.mkdir(new_dir_path, parents=True)
print(f"成功创建目录 {new_dir_path}")
# 验证目录是否存在
if fs.exists(new_dir_path):
    print(f"目录 {new_dir_path} 存在")
else:
    print(f"目录 {new_dir_path} 不存在")

代码说明：

• fs.mkdir() 方法的 parents=True 参数非常重要，类似于 Linux 命令 mkdir -p，可以自动创建多级目录。
• fs.exists() 方法用于判断路径（文件或目录）是否存在。

3.4.2 删除文件和目录

import s3fs
fs = s3fs.S3FileSystem()
# 删除单个文件
file_to_delete = 'my-s3-bucket/write_test.txt'
if fs.exists(file_to_delete):
    fs.rm(file_to_delete)
    print(f"成功删除文件 {file_to_delete}")
# 删除目录及目录下的所有内容，recursive=True 表示递归删除
dir_to_delete = 'my-s3-bucket/new-folder'
if fs.exists(dir_to_delete):
    fs.rm(dir_to_delete, recursive=True)
    print(f"成功删除目录 {dir_to_delete} 及其所有内容")

代码说明：

• fs.rm() 方法默认只能删除文件，删除目录时必须指定 recursive=True，否则会抛出异常。
• 删除操作不可逆，执行前请务必确认路径正确。

3.5 文件的重命名与移动

s3fs 提供 rename 方法实现文件的重命名和移动功能，该方法相当于 Linux 中的 mv 命令。

import s3fs
fs = s3fs.S3FileSystem()
# 原文件路径
original_path = 'my-s3-bucket/test.txt'
# 重命名后的路径
new_path = 'my-s3-bucket/renamed_test.txt'
# 文件移动：将文件移动到另一个目录
move_path = 'my-s3-bucket/new-folder/moved_test.txt'
# 重命名文件
fs.rename(original_path, new_path)
print(f"文件已从 {original_path} 重命名为 {new_path}")
# 移动文件，先确保目标目录存在
fs.mkdir('my-s3-bucket/new-folder', parents=True)
fs.rename(new_path, move_path)
print(f"文件已从 {new_path} 移动到 {move_path}")

代码说明：

• fs.rename(src, dst) 方法接收两个参数，src 是原路径，dst 是目标路径。
• 如果目标路径的目录不存在，移动操作会失败，因此需要提前创建目录。

四、s3fs 实际应用案例：云端数据处理

在数据科学和机器学习场景中，经常需要处理存储在 S3 中的大规模数据集。下面以读取 S3 中的 CSV 文件并进行数据分析为例，展示 s3fs 与 pandas 库的结合使用，实现云端数据的直接处理，无需下载到本地。

4.1 案例需求

读取 S3 存储桶中 my-s3-bucket/dataset 目录下的 sales_data.csv 文件，分析该文件的前 5 行数据、数据列名和数据类型，并计算销售额的平均值。

4.2 代码实现

import s3fs
import pandas as pd
# 创建 S3FileSystem 实例
fs = s3fs.S3FileSystem()
# S3 中 CSV 文件的路径
s3_csv_path = 'my-s3-bucket/dataset/sales_data.csv'
# 使用 s3fs 打开 CSV 文件，并通过 pandas 读取
with fs.open(s3_csv_path, 'r', encoding='utf-8') as f:
    df = pd.read_csv(f)
# 数据分析
print("=== 销售数据前 5 行 ===")
print(df.head())
print("\n=== 数据列名 ===")
print(df.columns.tolist())
print("\n=== 数据类型 ===")
print(df.dtypes)
print("\n=== 销售额平均值 ===")
# 假设销售额列名为 sales_amount
average_sales = df['sales_amount'].mean()
print(f"平均销售额：{average_sales:.2f}")

代码说明：

• s3fs 与 pandas 完美兼容，通过 fs.open() 打开的文件对象可以直接传入 pd.read_csv() 函数。
• 这种方式无需将 CSV 文件下载到本地，节省了本地存储空间，尤其适合处理 GB 级别的大型数据集。
• 运行代码前，需要确保 pandas 库已安装，可通过 pip install pandas 命令安装。

4.3 案例扩展：批量处理 S3 中的多个 CSV 文件

如果 S3 目录下有多个 CSV 文件，可以通过 fs.glob() 方法匹配所有 CSV 文件，然后批量读取和合并。

import s3fs
import pandas as pd
fs = s3fs.S3FileSystem()
# 匹配 S3 目录下所有的 CSV 文件
csv_files = fs.glob('my-s3-bucket/dataset/*.csv')
print(f"找到 {len(csv_files)} 个 CSV 文件")
# 批量读取并合并所有 CSV 文件
df_list = []
for file in csv_files:
    with fs.open(file, 'r', encoding='utf-8') as f:
        df_temp = pd.read_csv(f)
        df_list.append(df_temp)
        print(f"已读取文件：{file}")
# 合并所有 DataFrame
merged_df = pd.concat(df_list, ignore_index=True)
print(f"\n合并后的数据集总行数：{len(merged_df)}")
print("合并后数据前 3 行：")
print(merged_df.head(3))

代码说明：

• fs.glob() 方法支持通配符匹配，*.csv 表示匹配所有以 .csv 结尾的文件。
• pd.concat() 函数用于合并多个 DataFrame，ignore_index=True 表示重置合并后的索引。

五、s3fs 相关资源

• Pypi地址：https://pypi.org/project/s3fs
• Github地址：https://github.com/fsspec/s3fs
• 官方文档地址：https://s3fs.readthedocs.io/en/latest/

关注我，每天分享一个实用的Python自动化工具。