BaiduPCS-Rust: a Rust client for Baidu Netdisk with local encryption

A Netdisk client built because the official one was slow on a NAS

The project states its motivation plainly, and the reason is narrow rather than ideological. The author was already a Baidu Netdisk member, but the official client on a NAS could not reach the full speed of the membership bandwidth, which made the NAS use case frustrating.

The response is a client written in Rust with a Vue 3 interface, aimed at high performance downloads through multi-threaded concurrency and resumable transfers, with automatic backup of local files to the netdisk, a modern web interface with real-time progress, and support for Windows, Linux and macOS. The badges state the targets, Rust 1.87, Vue 3.3 and newer, Apache 2.0, and Docker ready.

It is not the first project in this space and the readme says so. The author credits qjfoidnh/BaiduPCS-Go, an enhanced version of which provides share link and instant transfer handling, and GangZhuo/BaiduPCS, the original command line client, for the open source work that made this possible.

The scale of the feature set deserves a note before reading further. The list covers account management, authentication, file browsing, download and upload engines, a share transfer feature, share synchronisation, offline downloads, automatic backup, network proxying, client-side encryption and a separate decryption tool, which is a lot of surface for a client application.

Accounts are isolated by owner_uid and threads are rationed by membership

Multi-account support is the part of the design that shapes the rest, because everything else is per account.

Accounts can be added, switched and deleted, each with its own session and its own task queue. Downloads, uploads, share transfers, backups and offline downloads are all isolated by owner_uid, so two accounts never share a queue or a credential.

The interesting part is how the machine's threads are divided. The total thread count is distributed across accounts according to membership weight, and each account shows a guaranteed minimum and a maximum. The readme gives the automatic recommendation by level, ten for an ordinary member and fifteen for a super member, which is a direct way of expressing what the membership tiers actually buy.

The interface reflects the same model. The avatar gets a coloured ring by membership type, plain for an ordinary member, yellow for VIP and purple for SVIP, with the specific level such as SVIP5 in the corner. There is an optional quick switch bar across the top when more than one account is logged in.

The cross-account features build on the same isolation. A file can be downloaded with a different account, by generating a share link and pulling it directly, which is the answer to a file that lives on an ordinary account while the fast membership sits on another. A default download account can be set. Copying and moving across accounts works through a temporary private share that is revoked immediately, and a move only puts the source file in the recycle bin after the copy is verified as consistent.

Login is a QR scan or a pasted cookie, and the web UI can require TOTP

Two login methods are offered, which is a pragmatic choice for a service with no public API.

The primary one is a QR code scanned with the Baidu Netdisk app, which is the normal way a person signs in. The second is a cookie login, where you paste the full cookie string copied from your browser developer tools. Automatic session management follows, with sessions persisted, the login state checked automatically, and an expired session redirecting to the login page.

The web interface has its own access control, which is optional. Password protection stops unauthorised access to the interface, and TOTP two-factor authentication is supported with apps such as Google Authenticator. There is a recovery code mechanism for the case where the TOTP device is lost, which is the detail that separates a usable deployment from one that locks you out of your own server.

That combination matters for the deployment model, because the server is normally reachable from a browser, sometimes over the internet. The rest of the security surface sits in the backup and encryption features, where the client holds the keys locally rather than sending plaintext to the server.

The download engine treats CDN links as a resource that expires

The download engine is the reason the project exists, so it carries the most detail.

A single file is fetched with multi-threaded concurrency, eight parallel segments by default and configurable. Folder downloads recurse and create the task tree automatically, and batch downloads handle several files or folders at once. Conflicts are handled by policy, with overwrite, skip and automatic rename available for single files, folders and batches. Resume is supported, and a speed limit can be set.

The interesting engineering is around link expiry. There is URL health management with an eviction strategy, and a three-layer detection mechanism for refreshing CDN links: detection of abnormal speed, detection of a stalled thread, and a scheduled forced refresh. A stalled transfer on a consumer broadband connection is otherwise invisible until the user notices nothing is arriving, and a scheduled refresh is the blunt instrument that keeps long transfers alive overnight.

The interface shows speed, progress percentage and estimated time remaining, with a queue that supports pause, continue and delete. A download directory picker keeps a memory of recent directories, and there is a button to open the download folder in the system file manager, which falls back to copying the path when the server is running in Docker or being reached remotely.

The upload engine mirrors it, with one entry point for files and folders, batch upload, conflict policies including smart de-duplication, pause, continue, retry and delete, a marker for instant upload when the backend supports it, and a link that jumps to the corresponding directory in the netdisk.

Share sync diffs against a snapshot, offline download predicts its own polling

Two features handle the long-running work, and both are built around not re-downloading what has not changed.

Share sync subscribes to a share link and pulls it on a schedule, comparing the result against the previous snapshot and transferring only the files that changed. A subscription can be configured per account, can target both the netdisk and a local directory, and can filter by include and exclude paths. Conflicts are resolved by overwriting, keeping a new version or skipping, and whether deletions follow the sharer is a setting, with the default being to keep the old file. Progress is live, with per-file progress when a folder is being synced, and each run leaves a history of added, modified, removed and failed items.

Offline download hands the fetch to the Baidu servers, which then deliver into the netdisk. HTTP and HTTPS links, magnet links and ed2k links are supported, with magnet links normalised from Base32 to hex automatically. Tasks can be added, queried, cancelled and deleted, and the readme describes a smart polling mechanism that predicts the completion time from the progress and adjusts the interval between polls, with a minimum of three minutes and a maximum of sixty. Progress is pushed over WebSocket rather than polled by the browser.

Automatic backup is the third long-running job, running in both directions, local to cloud and cloud to local, with a filesystem watcher on Windows using ReadDirectoryChangesW and a scheduled polling fallback for platforms where the watcher misses changes.

Client-side encryption hides the file type, and the key is yours to lose

The encryption feature is the one with the most operational consequences, and the readme is unusually direct about the risk.

Files are encrypted with AES-256-GCM before upload, giving end-to-end protection, and it can be applied to ordinary uploads or to automatic backups. Keys can be generated, exported and deleted from the interface. Encrypted files carry the .dat extension, which hides the real file type from the netdisk, and the original filename is restored in the file list so the user interface stays readable while the stored object does not.

The mapping between encrypted and original names lives in the database, and the naming scheme deserves attention because it explains why the folder handling is not obvious. Each encrypted file gets a unique UUID name such as a1b2c3d4-xxxx.dat. Folders use a path-aware strategy keyed on the pair of parent path and folder name, so a folder called docs under /backup/a and a folder called docs under /backup/b get different UUIDs and are stored as separate mappings.

The warning at the end of the section is the part to read twice. The encryption key file config/encryption.json and the database config/baidu-pcs.db, which holds the mapping table, must be backed up, or the encrypted files cannot be decrypted.

Because of that, the project ships a separate decryption tool, decrypt-cli, that runs without the main application, handles both batch and single file decryption, supports AES-256-GCM and ChaCha20-Poly1305, and runs on Windows, Linux and macOS:

decrypt-cli decrypt --key-file encryption.json --map mapping.json --in-dir ./encrypted --out-dir ./decrypted

A single file uses a different set of arguments, and a key version can be named when the file was encrypted with a specific one:

decrypt-cli decrypt --key-file encryption.json --in file.dat --out file.txt --key-version 2

A compose file with a health check and a WAL directory

Deployment is documented as a Docker workflow, and the compose file shows the shape of a running instance.

The service is built from the repository Dockerfile, published on port 18888, and five directories are mounted from the host: config, downloads, data, logs and wal. The last of those is the one to notice, because a write-ahead log directory is what lets task state survive a restart rather than being rebuilt from memory.

The environment sets RUST_LOG to info and RUST_BACKTRACE to 1, which is the combination you want in a container that might crash, since the backtrace is the first thing anyone will ask for. The restart policy is unless-stopped, and the health check is a curl against the health endpoint:

test: ["CMD", "curl", "-f", "http://localhost:18888/health"]
interval: 30s
timeout: 5s
retries: 3

The comments next to that check explain the timing, with the start period giving the Rust application room to initialise its state and load sessions, and the longer timeout avoiding a false failure from a slow response during startup.

The repository also carries a development compose file and an image compose file, plus a rustfmt.toml and a commitlint configuration, which suggests a project with a defined style rather than an ad hoc script. The release line is 2.3.x, with 2.3.0 on 2026-10-12, 2.3.1 on 2026-10-16 and 2.3.2 on 2026-10-17, and the last push was on 2026-10-19.

Editorial conclusion

BaiduPCS-Rust fits a Netdisk member who runs a NAS or a home server and needs the member download speed on a machine the official client does not support well, because the download engine is segmented, resumable and scheduled around a quota of threads per account. It is the wrong choice if you are not willing to look after the key files, because the encryption section of the readme warns that config/encryption.json and config/baidu-pcs.db must be backed up or the encrypted files cannot be decrypted, and it is the wrong choice if you only want to browse files, since the web interface exists for a server that stays on. Before you enable encryption, export the key and the mapping file and store them somewhere else, and before you trust the downloader on a metered connection, read the conflict and resume behaviour rather than the speed numbers.

Frequently asked questions

Official sources

1. Issues
2. komorebiCarry/BaiduPCS-Rust on GitHub
3. License: Apache-2.0
4. README
5. Releases