对象存储
对象存储
对象存储
文档指南
请输入
产品动态
产品公告
产品计费
快速入门
用户指南
存储桶管理
基础设置
容错与容灾
ObjectSet
文件管理
监控与告警
权限配置
IAM 策略管理
典型配置场景
IAM 子用户授权
使用工具及 SDK 的授权说明
接入点
单区域接入点（SRAP）
内容感知与处理（SenseFlow）
TOS Agent
数据处理
分层命名空间（HNS）
TOS Vectors
API 参考
向量桶
SDK 参考
Python-Vectors
向量桶
向量索引
Java-Vectors
向量桶
向量索引
Node.js-Vectors
向量桶
向量索引
工具指南
tosutil
常用命令
辅助命令
TOS Browser
FSX
TOS PyTorch Connector
tosfsspec
API 参考
签名机制
存储桶
桶基础操作
自定义域名
数据处理
媒体处理
视频转码
音频转码
ObjectSet
生命周期
对象
基础操作
分片上传
SDK 参考
Java
存储桶接口
管理桶配置
ObjectSet
对象接口
下载对象
数据处理
视频处理
日志配置
分层命名空间
Python
数据处理
存储桶接口
对象接口
上传对象
C++
存储桶接口
对象接口
Go
对象接口
存储桶接口
管理桶配置
ObjectSet
数据处理
日志配置
Node.js
存储桶接口
对象接口
上传对象
数据处理
Browser.js
上传对象
.NET
对象接口
PHP
对象接口
异常处理
Android
对象接口
iOS
对象接口
Harmony
存储桶接口
对象接口
上传对象
Rust
存储桶接口
桶基础操作
桶清单
自定义域名
对象接口
基础操作
错误码
01-SERVICE_ERROR
02-AUTH
03-ACCESS_CONTROL
04-QOS
05-REQUEST
06-BUCKET
07-LIFECYCLE
08-ACL
09-CORS
10-POLICY
11-MIRROR
12-REPLICATION
13-WEBSITE
14-NOTIFICATION
15-ENCRYPT
16-CUSTOMDOMAIN
17-OBJECT
18-TAG
19-MULTIPART
20-STORAGE_CLASS
21-CALLBACK
22-DATA_PROCESS
23-BATCH
24-STORAGE_LENS
25-INVENTORY
26-DIRECTORY_BUCKET
32-WORM
常见问题
最佳实践
AIGC-豆包大模型最佳实践
校验数据一致性
- 文档首页
对象存储SDK 参考Python快速入门（Python SDK）
复制全文
下载 pdf快速入门（Python SDK）
文档反馈
问问助手本文介绍如何通过 TOS Python SDK 来完成常见的操作，如创建桶、上传对象、下载对象和删除对象等。
前提条件
注意事项
多进程场景下需要创建多个 TosClient，不能共享同一个 TosClient，否则会有多进程并发安全问题，可能会导致读写请求数据错乱。
安装 Python
安装 python-devel
您需要安装 python-devel 包。
TOS Python SDK 依赖 crcmod 计算 CRC 校验码，而 crcmod 的 C 扩展模式依赖 python-devel 包中的 Python.h 文件。如果缺少 Python.h，crcmod 的 C 扩展模式安装失败，crcmod 会运行在纯 Python 模式，纯 Python 模式计算 CRC 性能远差于 C 扩展模式 ，会导致上传、下载等操作效率低下。
说明
如果开启 CRC 校验导致上传下载性能差，您可以关闭 CRC64 校验。
验证 crcmod 模式
进入 Python 环境，输入 import crcmod._crcfunext。
- 如果出现以下错误提示，则表明 crcmod 库的 C 扩展模式安装失败，crcmod 库是纯 Python 方式。原因是编译 crcmod 时，_crcfunext.so 依赖 Python.h 文件，而系统中缺少这个头文件，因此 _crcfunext.so 库生成失败。
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ImportError: No module named _crcfunext
- 如果没有出现错误提示，则表明 crcmod 库的 C 扩展模式安装成功。
如果出现错误，可以按照以下方式解决：
- 卸载 crcmod。
- pip uninstall crcmod
- 安装 python-devel。
- 如果您是 Windows 和 Mac OS X 系统，在安装 Python 的时候会将 Python 依赖的头文件一并安装，因此您无需安装 python-devel。
- 如果您是 CentOS、RHEL、Fedora 系统，可以使用以下命令安装：
- # Python2.x版本yum install python-devel# Python3.x版本yum install python3-devel
- 如果您是 Debian、Ubuntu 系统，您可以使用以下命令安装：
- # Python2.x版本apt-get install python-dev# Python3.x版本apt-get install python3-dev
- 重新安装 crcmod。
- pip install crcmod
示例代码
客户端通用示例
以下代码是使用 TOS Python SDK 的通用代码模版。
import os
import tos
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket = "bucket-test"
key = "object-test"
data = "Hello world"
try:
# 创建TosClientV2对象
client = tos.TosClientV2(ak, sk, endpoint, region)
# 调用接口请求TOS服务，例如上传对象
resp = client.put_object(bucket, key, content=data)
print('success, request id {}'.format(resp.request_id))
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print('fail with server error, code: {}'.format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print('error with request id: {}'.format(e.request_id))
print('error with message: {}'.format(e.message))
print('error with http code: {}'.format(e.status_code))
print('error with ec: {}'.format(e.ec))
print('error with request url: {}'.format(e.request_url))
except Exception as e:
print('fail with unknown error: {}'.format(e))
创建桶
存储桶（Bucket）是 TOS 的全局唯一的命名空间，相当于数据的容器，用来储存对象数据。以下代码用于创建一个新存储桶 bucket-test。
import os
import tos
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
key = "object-test"
data = "Hello world"
try:
# 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
client = tos.TosClientV2(ak, sk, endpoint, region)
# 设置桶存储桶为私有读写权限
client.create_bucket(bucket_name, acl=tos.ACLType.ACL_Private)
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print('fail with server error, code: {}'.format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print('error with request id: {}'.format(e.request_id))
print('error with message: {}'.format(e.message))
print('error with http code: {}'.format(e.status_code))
print('error with ec: {}'.format(e.ec))
print('error with request url: {}'.format(e.request_url))
except Exception as e:
print('fail with unknown error: {}'.format(e))
上传对象
新建存储桶成功后，可以往存储桶中上传对象，以下代码将字符串上传到 TOS 桶 bucket-test 中。
import os
import tos
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
object_key = "object-test"
try:
client = tos.TosClientV2(ak, sk, endpoint, region)
# 通过字符串方式添加 Object
client.put_object(bucket_name, object_key, content='Hello World')
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print('fail with server error, code: {}'.format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print('error with request id: {}'.format(e.request_id))
print('error with message: {}'.format(e.message))
print('error with http code: {}'.format(e.status_code))
print('error with ec: {}'.format(e.ec))
print('error with request url: {}'.format(e.request_url))
except Exception as e:
print('fail with unknown error: {}'.format(e))
下载对象
以下代码用于将指定的 TOS 对象下载到内存中。
import os
import tos
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
object_key = "object-test"
try:
# 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
client = tos.TosClientV2(ak, sk, endpoint, region)
# 下载对象到内存中
object_stream = client.get_object(bucket_name, object_key)
# object_stream 为迭代器可迭代读取数据
# for content in object_stream:
# print(content)
# 您也可调用 read()方法一次在内存中获取完整的数据
print(object_stream.read())
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print('fail with server error, code: {}'.format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print('error with request id: {}'.format(e.request_id))
print('error with message: {}'.format(e.message))
print('error with http code: {}'.format(e.status_code))
print('error with ec: {}'.format(e.ec))
print('error with request url: {}'.format(e.request_url))
except Exception as e:
print('fail with unknown error: {}'.format(e))
列举对象
以下代码用于列举指定桶 bucket-test 中的对象，最多可列举 2000 个。
import os
import tos
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
object_key = "object-test"
try:
# 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
client = tos.TosClientV2(ak, sk, endpoint, region)
# 默认单次列举最多1000个对象
list_out_1 = client.list_objects(bucket_name)
for ob in list_out_1.contents:
print(ob.key)
# 若未列举完对象，可设置可选参数marker继续列举
if list_out_1.is_truncated:
list_out_2 = client.list_objects(bucket_name, marker=list_out_1.next_marker)
for ob in list_out_2.contents:
print(ob.key)
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print('fail with server error, code: {}'.format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print('error with request id: {}'.format(e.request_id))
print('error with message: {}'.format(e.message))
print('error with http code: {}'.format(e.status_code))
print('error with ec: {}'.format(e.ec))
print('error with request url: {}'.format(e.request_url))
except Exception as e:
print('fail with unknown error: {}'.format(e))
删除对象
以下代码用于删除指定桶 bucket-test 中的对象 object-test。
import os
import tos
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
object_key = "object-test"
try:
client = tos.TosClientV2(ak, sk, endpoint, region)
# 从桶中删除对象
client.delete_object(bucket_name, object_key)
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print('fail with server error, code: {}'.format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print('error with request id: {}'.format(e.request_id))
print('error with message: {}'.format(e.message))
print('error with http code: {}'.format(e.status_code))
print('error with ec: {}'.format(e.ec))
print('error with request url: {}'.format(e.request_url))
except Exception as e:
print('fail with unknown error: {}'.format(e))
关闭 TosClient
TOS Python SDK 默认开启长连接，您创建多个 TosClient 实例访问 TOS 后，可使用以下代码关闭不再使用的 TosClient 实例，释放连接资源。
import os
import tos
# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
try:
# 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
client = tos.TosClientV2(ak, sk, endpoint, region)
# 执行相关操作后，将不再使用的TosClient关闭
client.close()
except tos.exceptions.TosClientError as e:
# 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
# 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
print('fail with server error, code: {}'.format(e.code))
# request id 可定位具体问题，强烈建议日志中保存
print('error with request id: {}'.format(e.request_id))
print('error with message: {}'.format(e.message))
print('error with http code: {}'.format(e.status_code))
print('error with ec: {}'.format(e.ec))
print('error with request url: {}'.format(e.request_url))
except Exception as e:
print('fail with unknown error: {}'.format(e))
相关文档
- 关于创建桶的更多信息，请参见创建桶与 CreateBucket。
- 关于列举对象的更多信息，请参见列举对象与 ListObjects。
- 关于删除对象的更多信息，请参见删除对象与 DeleteBucket。
最近更新时间：2026.07.06 10:36:23
这个页面对您有帮助吗？
有用
有用
无用
无用