aligo is a Python SDK for Aliyun Drive built around file_id

A driver for Aliyun Drive, not a general cloud storage SDK

aligo is described in the repository description as a simple, easy to use and extensible API library for Aliyun Drive, and the pyproject.toml gives the shorter description aliyun drive sdk. The scope is one specific service. If your storage is S3, OSS or anything else, this library is not for you. What it does cover is wide for a single service. The feature list in the README runs from persistent login and multiple account login, through folder synchronisation, online decompression, file and tag search, duplicate file listing, renaming, upload and download, moving and copying, deletion and restore, document preview, sharing, saving and favouriting, account and capacity information, and album creation, deletion, modification and file listing. The audience is Python developers automating a personal or team drive, and the examples directory shows the shape of that work. There are 23 numbered examples covering a quick start, multiple user login, uploading a desktop folder, downloading a folder, uploading to a specific drive location, checking whether a file exists, online decompression, a custom subscription feature, a custom email sender, redeeming a welfare code, cleaning up large files, extracting share information, getting an album drive_id, walking files, exporting share contents, saving everything from a share, downloading a file from a share directly, cancelling a share, creating a custom share, automatic check in, dealing with throttling, and uploading bytes data directly. The design goal stated in the README is that the library gives complete code hints in an editor, so a caller can see the shape of what a method returns without reading the wiki.

file_id is the real address of a file, and paths are a convenience

This is the single most useful thing the README teaches about Aliyun Drive, and it is a property of the service rather than of the library. The README explains that Aliyun Drive locates files by file_id rather than by name or path, and that file_id is the only way to identify a file uniquely. The library provides get_file_by_path and get_folder_by_path to fetch a file object from a drive path, and the file_id attribute on that object then gives you the identifier you actually need for other calls. The README also warns against calling those helpers frequently, because internally they work by walking the file list with get_file_list. That is a real performance characteristic rather than a stylistic note: a path lookup is a directory traversal, so a loop that resolves paths one at a time will enumerate the drive repeatedly. The returned objects are richer than their printed form. The quick start example makes this explicit, noting that print(file) shows only part of the information while the file object has many more attributes, and the example prints file.file_id, file.name and file.type explicitly. The datclass dependency in requirements.txt is what produces these structured return values instead of raw dictionaries. The second structural point is drives. The drive is not a single namespace. The examples show list_my_drives returning drives, a v2_user_get call exposing resource_drive_id, and get_file_list accepting a drive_id argument. A comment even shows how the default drive can be changed with ali.default_drive_id.

Installing and running the quick start

The package is published on PyPI as aligo, and the README gives two installation lines, one from the index and one from the Git repository.

pip install -U aligo
pip install git+https://github.com/foyoux/aligo.git

The first line installs the newest published version with upgrade, the second installs from source for people who need the tip of main. The project metadata says it requires Python 3.7 or higher, and the classifiers list 3.7 through 3.11. The quick start is short enough to read in one go.

"""快速入门"""
from aligo import Aligo

if __name__ == '__main__':
    ali = Aligo()  # 第一次使用，会弹出二维码，供扫描登录

    user = ali.get_user()  # 获取用户信息
    print(user.user_name, user.nick_name, user.phone)  # 打印用户信息

    file_list = ali.get_file_list()  # 获取网盘根目录文件列表
    for file in file_list:  # 遍历文件列表
        # 注意：print(file) 默认只显示部分信息，但是实际上file有很多的属性
        print(file.file_id, file.name, file.type)  # 打印文件信息

What you should see on the very first run is a QR code, because the constructor with no credentials triggers the scan to log in. After that the token is persisted and later runs reuse it. The dependencies explain the rest of the experience: requests for HTTP, qrcode with the pil extra and qrcode_terminal for the login code, coloredlogs for readable output, tqdm for progress bars on transfers, and datclass for the returned objects.

Three ways to log in, and where the tokens are stored

Login is the part of the library with the most moving pieces, and the README documents three arrangements. The default is a web QR code scan. A `port` argument can be supplied, in which case you open a browser at http://<YOUR_IP>:<port> and scan from there.

from aligo import Aligo

# 提供 port 参数即可, 之后打开浏览器访问 http://<YOUR_IP>:<port>
ali = Aligo(port=8080)

The second is sending the login QR code to an email inbox, which the README marks as the recommended option. It uses an EMailConfig object, and the note recommends binding the mailbox to WeChat so that a login request arrives promptly and an expired login can be noticed quickly.

from aligo import Aligo, EMailConfig

if __name__ == '__main__':
    email_config = EMailConfig(
        email='<接收登录邮件的邮箱地址>',
        # 自配邮箱
        user='',
        password='',
        host='',
        port=0,
    )
    ali = Aligo(email=email_config)

The third is the configuration folder, which is what makes multi account use practical. The default location is <user directory>/.aligo, and set_config_folder changes it before any Aligo object is created. Each account is a named JSON file.

from aligo import set_config_folder, Aligo

if __name__ == '__main__':
    # 创建 Aligo 对象前，先设置配置文件目录，默认是 <用户目录>/.aligo
    set_config_folder('/home/aligo')
    # 会创建 /home/aligo/小号1.json 配置文件
    ali1 = Aligo(name='小号1')
    # 会创建 /home/aligo/小号2.json 配置文件
    ali2 = Aligo(name='小号2')

The ordering constraint matters: set_config_folder has to run before the constructor, because the file is written when the account is created.

Extending the client for endpoints the library does not wrap

The extension story is unusual and worth understanding, because it explains the difference between aligo and a hardcoded wrapper. The README gives three steps: observe the communication with a browser or a packet capture tool, obtain the url or path plus the request body, and then inherit from Aligo and use the existing methods such as self._post to send the request. The token is maintained automatically, so the extension author only has to worry about how to send the request.

# 继承 `Aligo`, 使用现有的方法 `self._post` 等，进行发送请求；
# 会自动维护 **token**, 你只需关注如何发送请求即可

For interfaces that are not commonly used and therefore not wrapped, the same trick applies, as the README notes in the installation section: you can call self.post directly to send a request to an endpoint the library does not expose. That mechanism is what keeps the package maintainable in the face of a changing API. When the vendor adds an endpoint, you do not need a new release, and when the vendor changes one, you can patch around it before an upstream fix lands. The cost is that the extension surface is not a stable public contract. It depends on internal method names, so a refactor inside the library can break your subclass even when the library's own API is unchanged.

Limits the library documents about itself, including the delete it will not offer

Several caveats in the README are the kind that only appear in a project that has been used against a live service. The first is about interface churn. The installation notes say the official API was recently updated, which means get_file_list can no longer return a download link directly and get_download_url has to be called separately. A second note says the interfaces change often, that problems should be reported, and that fixes will come as fast as possible. The client is a mirror of someone else's API, and the mirror moves. The second is the share lifetime. Because instant transfer links expire, the README notes that the validity period of custom share information is only four hours. Any workflow that stores a share link and uses it later has a hard deadline. The third is a behaviour that looks like a bug but is not. When saving a very large share with share_file_save_all_to_drive, the call returns immediately but the files are not yet in your drive, because the Aliyun Drive server continues to copy them in the background. Seeing only part of the share after the call returns is normal. The fourth is the most interesting. The README explains how to delete a file permanently, bypassing the recycle bin, and then says this feature is too dangerous so aligo does not provide it directly. The wiki page extends the functionality and warns to use it carefully. A library that deliberately omits an endpoint is a design stance, and it means the destructive operation is one class of code away rather than one method call.

GPL-3.0, a src layout, and a release trail that stopped in January

The licence field on the repository says GPL-3.0, which is the decision most likely to affect whether you can ship this in a product. A copyleft licence means that distributing a derivative work, including a linked application, carries obligations that a permissive licence would not. That is a question for your legal counsel, not for this article. Structurally, the project is a src layout package. The pyproject.toml declares a setuptools build with setuptools>=61.0, sets the package directory with tool.setuptools.packages.find where src, and takes both the version and the dependency list dynamically: the version comes from the aligo.__version__ attribute and the dependencies are read from requirements.txt. The top level entries are examples/, images/, src/, tests/, a requirements.txt and a pyproject.toml. On maintenance, the picture is mixed. The last push was on 2026-09-05, so work continues, but the tagged releases stop earlier: v6.2.8 on 2026-01-15, v6.2.7 on the same day at a slightly earlier time, and v6.2.6 on 2025-02-06. Two patch releases published minutes apart suggests a packaging step rather than two feature releases. The README ends with a disclaimer that the project is for study and exchange and asks to be removed if it causes any trouble. Read together with the note about the vendor changing interfaces, that tells you how to treat this dependency: it is a convenience layer you should be prepared to patch, and one you should pin to a known version rather than track blindly.

Editorial conclusion

Adopt aligo when your project needs to drive Aliyun Drive from Python and you can tolerate a client that has to be updated when the vendor changes its endpoints. Do not adopt it in a closed source product without reading the GPL-3.0 obligations, and do not adopt it if you need a permanent delete, since the library does not provide one. Before shipping, check the current release of the client against the endpoints your code calls, because the README already records a case where an upstream change broke download link retrieval in get_file_list.

Frequently asked questions

Official sources

1. foyoux/aligo on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases