123pan is a third-party desktop client for a Chinese cloud drive

The origin is a traffic cap and an Android protocol

123pan is a third-party desktop client for the 123 cloud drive, and the package description states the problem directly: it solves the problem of the 123 cloud drive PC client limiting daily self-use traffic to 1 GB.

That is a narrow, specific motivation, and it explains the rest of the design. The project simulates the Android client protocol in order to improve the self-use traffic limit of the official PC client, and it also provides file management, upload and download, offline download, folder sync and multi-account management.

The stack is stated as Python, PySide6 and PySide6-Fluent-Widgets, which is the fluent design system for Qt used across the interface. The topic tags confirm the choice, with pyside6, qt6, fluent-design, gui-application and requests among them.

Two disclaimers frame everything. The first is in the project introduction: this project is unrelated to the official 123 cloud drive, the client's capabilities depend on the 123 cloud drive server interfaces, and some features may change as server-side policy adjusts. The second is in the download section, and it is longer: the project is for personal learning and technical research only, has no affiliation with 123 cloud drive, software is provided as is with no guarantee, users should bear the risks of data loss, account restrictions and service interruption themselves, and should comply with the 123 cloud drive user agreement and relevant laws, and the software should not be used for commercial purposes.

That last clause is the one to read carefully if you are considering it for anything other than personal use.

The project is GPL-3.0 licensed, and the code is hosted on both GitHub and Codeberg. The last push was on 2026-10-22 with releases v4.0.7 from 2026-10-03, v4.0.6 from 2026-09-25 and v4.0.5 from 2026-09-11. The default branch is fluent-dev, and the topic list includes uv, which tells you the dependency and build tooling.

Running it, and the one packaging trap

There are three ways to get it and each has a wrinkle.

The first is a release build. You go to the GitHub Releases page and download the version matching your system. Windows, Linux and macOS builds are provided, with the exact available platforms and architectures given in the attachment notes for each release. After extracting, you run 123pan.exe on Windows, 123pan on Linux, or open the macOS application bundle.

The wrinkle is documented immediately after. The current Nuitka packaging artefacts may fail to start in a path containing non-ASCII characters. If the release exits immediately after launch, extract the program completely into an all-English path and try again. Running from source is not affected by that restriction.

That is a specific and plausible failure. A Chinese user on Windows very often has a user directory with a Chinese name, and a Nuitka build that cannot start from that path is a bad first impression for the whole project. The workaround is documented and the FAQ repeats it as step three of the troubleshooting list.

The second way is from source. You need Python 3.12 or higher and uv installed beforehand:

git clone https://github.com/123panNextGen/123pan.git
cd 123pan
uv sync
uv run src/123pan.py

And if you want to contribute, you can install the test, lint and build dependencies as needed:

uv sync --group test --group lint --group build

The third is the AUR, for Arch Linux and derivatives:

yay -S 123pan

The uv-based source workflow is worth a second look, because the dependency groups named in that command, test, lint and build, tell you the project has a real development setup rather than a single script. There is a script/ directory at the repository root with a lint.sh in it, and a pyproject.toml with a .pylintrc alongside it.

The package metadata gives the version as 4.0.7, requires Python 3.12 or higher, and depends on pyside6 at 6.10 or newer and pyside6-fluent-widgets at 1.11.1 or newer.

File management, transfers and the features that need the server

The feature list is organised into seven groups, and the split between what the client does locally and what it asks the server to do is the interesting structure.

The file management group is entirely local. A directory tree and a table view with search, sorting, breadcrumb navigation and column width adjustment. Creating folders, renaming, moving, copying and deleting files. Multi-target copying and copying files into a specified directory. Recycle bin restore and permanent deletion. And management of free and paid shares, creating, copying and deleting share links.

The upload and download group is where the interesting engineering sits. Multi-threaded chunked downloads with resume, and backoff retry on 429 and 5xx errors. Chunked uploads with resume and instant upload. Folder upload with progress validation before starting. Pause, resume, cancel and priority adjustment on upload and download tasks. Upload and download speed limits, plus settings for thread count and number of concurrent tasks. Live speed, progress and task status display. And HTTP or SOCKS5 proxies for downloads.

The offline download and instant upload group depends on the server rather than the client. It supports HTTP, HTTPS, Magnet and Thunder links, with the offline download performed by the 123 cloud drive server. It imports 123FastLink or compatible instant-upload JSON data, and it exports instant upload links and JSON data so they can be shared across clients.

So there is a category of feature that is really a thin client over a server-side API. That matters for the stability question the project raises itself, since the capability is the server's, not the app's.

The remaining groups are folder sync, login and accounts, file preview, and interface and settings.

Folder sync is one-way, from a local folder to a cloud directory, with manual sync and scheduled sync at 30 seconds, 1 minute, 5 minutes, 30 minutes and 1 hour. There is an option to delete cloud files when the local file is deleted, and options to close to the system tray and to minimise on login.

Login supports account and password as well as scanning a QR code with the 123 cloud drive app. Multiple accounts can be saved and switched quickly. And there is an Android device model emulation option.

The previews cover PNG, JPEG, WebP, GIF, SVG and other common image formats, TXT, Markdown, JSON, Python, JavaScript and other common text and code formats, plus PDF, audio and video.

The interface group is where the fluent design work shows: a Simplified Chinese and English interface, a theme that follows the system with light and dark options, the Windows 11 Mica effect and window transparency adjustment, and a configurable log level with logs kept for the most recent seven days.

The virus scanner warning, and how the project answers it

The frequently asked questions section has four entries, and the first one is the one every new user will search for.

Why does the antivirus software report a risk? The releases are not code signed for now, so some security software may produce a false positive. You should only download from GitHub Releases or the project website, and you can check the program's behaviour against the source code in this repository.

That answer is honest and reasonable. Unsigned Windows executables do get flagged, and the fact that the project points you at its own source as the way to verify the behaviour is the correct response. The alternative, a paid code signing certificate, is a real cost for an open source project run by a team rather than a company.

The second entry, the program will not start or exits immediately, is a numbered list of four steps. Confirm you downloaded the version for your operating system and processor architecture. Extract the release completely before running it rather than starting it inside the archive. If the program sits in a Chinese or other non-ASCII path, move it to an all-English path and try again. And Windows users can check the security software's interception records, while those running from source should confirm the Python version is 3.12 or higher and that uv sync has been run.

So two of the four steps are about the non-ASCII path issue, which tells you how often it comes up in practice.

The third entry is about slow downloads, and the answer is to adjust the download thread count, the maximum number of concurrent downloads and the speed limit in the settings under download settings. If a network proxy is enabled, you should also check whether the proxy link is the bottleneck. The actual speed is still affected by the network environment, the account state and server-side policy.

That last clause is the recurring theme of the whole project. Every capability and every limitation ultimately traces back to what the server permits.

The fourth entry is how to report an issue, and the guidance is to search the existing issues first, and to include the system version, the client version, the steps to reproduce and redacted logs.

Shortcuts, tests and the shape of the project

The keyboard shortcut table is short and it is the kind of list that tells you the interface conventions, with F5 to refresh the file list, Ctrl+N for a new folder, Ctrl+U to upload a file, Ctrl+D to download the selected items, Delete to delete the selected items, F2 to rename the selected item, Backspace to go back to the parent directory, Ctrl+F to focus the search box, Ctrl+A to select all files, and Enter to enter a folder or preview a file.

The development section points at three documents: a contribution guide, a development wiki at doc/wiki.md, and a development plan at doc/TODO.md.

And the common commands are these:

uv run pytest
uv run pytest tests/unit/
uv run pytest --cov
./script/lint.sh

So the test suite is pytest, with a unit test subdirectory, a coverage mode, and a shell script for the lint check.

The repository layout is consistent with a Python application that has a proper development setup. There is src/ for the application, tests/ for the test suite, doc/ for the documentation and images, script/ for the shell helpers, and pyproject.toml with a uv.lock pinning the dependency tree. There is a .pylintrc for linting, an AGENTS.md, a CODE_OF_CONDUCT.md, a SECURITY.md, and a CONTRIBUTING.md. There are also .trae/ and .vscode/ directories, which are editor configurations.

The community channels are GitHub Issues, GitHub Discussions and a QQ group, and the acknowledgement section thanks an earlier project for providing ideas.

One thing that stands out is the combination of hosting. The code is synchronised between GitHub and Codeberg, and there is a note about the distribution issue in the FAQ pointing users to GitHub Releases or the project website. Two hosts for the source and one for the binaries is a sensible arrangement given how release hosting works in China, and it is the kind of detail that only shows up in projects with an audience there.

Editorial conclusion

Adopt 123pan if you use the 123 cloud drive and the official client's daily traffic cap is a real constraint for you, since the client provides file management, resumable transfers, offline download and folder sync. Skip it if you need a signed, supported client, since the releases are not code signed and some security software flags them, and if you want to use it commercially, because the disclaimer restricts it to personal study and technical research. Verify first that you download from the GitHub releases or the project site rather than a mirror, that you extract to a path with only ASCII characters if the packaged build refuses to start, and what the current server-side policy allows, since the client depends on unofficial endpoints.

Frequently asked questions

Official sources

1. 123panNextGen/123pan on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases