SecretFlow: A Device Abstraction for Privacy-Preserving Computation
A unified framework for privacy-preserving data analysis and machine learning
At a glance
- What is it?
- SecretFlow wraps MPC, homomorphic encryption, TEE and differential privacy behind a single Python device abstraction, so the same data analysis and ML code can run across horizontally or vertically partitioned data. The design is coherent, but the released versions carry a b0 suffix and the README warns against production use.
- Who is it for?
- SecretFlow is aimed at teams that already know which privacy-enhancing technique their data split requires and want one Python surface for it. If you only need a single protocol, a narrower library such as HEU or SCQL is less machinery to carry.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 145 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem SecretFlow addresses: one API across several cryptographic protocols
Privacy-preserving machine learning is fragmented by protocol. Secure multiparty computation, homomorphic encryption, trusted execution environments and differential privacy each have their own libraries, their own data layouts and their own failure modes. A team that starts with MPC and later needs a TEE for a different workload usually rewrites the pipeline. SecretFlow's stated goal is to remove that rewrite. The README describes it as "a unified framework for privacy-preserving data intelligence and machine learning", built on four layers: an abstract device layer of plain devices and secret devices, a device flow layer that models higher algorithms as device object flow and a DAG, an algorithm layer for analysis and ML over horizontally or vertically partitioned data, and a workflow layer that integrates data processing, model training and hyperparameter tuning. The audience is therefore not a data scientist who wants a drop-in scikit-learn replacement. It is an engineer or platform team that must support several privacy techniques under one runtime and is willing to learn the device vocabulary first.
How the device layer and DAG carry a computation
The central mechanism is the split between plain devices and secret devices. A plain device holds data in the clear, as a normal Python process would. A secret device encapsulates a cryptographic protocol and exposes the same kind of object interface, so an operation written against a device object does not need to know whether the bytes underneath are being computed on by MPC, HE or a TEE. The device flow layer then arranges those device objects into a DAG, which is how a multi-step algorithm becomes a graph of device operations rather than a sequence of imperative calls. Above that, the algorithm layer is where the data partition matters: horizontal partitioning means parties hold different rows of the same schema, vertical partitioning means they hold different columns of the same rows. The README lists both as supported. The workflow layer sits on top to tie preprocessing, training and hyperparameter tuning into one run. One consequence worth stating plainly: the abstraction is only as good as the protocol coverage behind it. If a secret device for your protocol does not exist, the DAG cannot paper over the gap.
Installation and deployment: what the repository actually points you to
The README does not inline install commands. It redirects: "Please check INSTALLATION.md" under docs/getting_started/installation.md, and "Please check DEPLOYMENT.md" under docs/getting_started/deployment.md. That is a deliberate choice and it means the install path is versioned with the docs rather than with the README, which is the right place for it but also means you cannot evaluate the setup cost from the README alone. What the repository does expose is the surrounding project set. Kuscia is described as "a lightweight privacy-preserving computing task orchestration framework based on K3s", which is the piece that turns a single-process SecretFlow program into a multi-party deployment. SPU is "a provable, measurable secure computation device", HEU is a homomorphic encryption algorithm library, and YACL is a C++ library containing cryptography, network and io modules that other SecretFlow code depends on. So a realistic deployment is not one pip install. It is SecretFlow plus, depending on your topology, Kuscia for orchestration and the underlying device libraries. The Python package is the visible tip of a stack with C++ components underneath.
The b0 release tag is the first thing to check
Every recent release listed for this repository carries a b0 suffix: v1.14.0b0 from September 2025, v1.13.0b0 from July 2025, v1.12.0b0 from April 2025. The README's disclaimer is explicit: "Non-release versions of SecretFlow are prohibited from using in any production environment due to possible bugs, glitches, lack of functionality, security issues or other problems." Read those two facts together and the practical position is that the published artifacts at the time of writing are beta-tagged, and the project itself tells you not to run non-release versions in production. That is not a criticism of the code; it is a statement about what the version numbers mean. If your evaluation depends on a stable, supported release line, you need to confirm from the release notes or the installation guide which artifacts are treated as releases, because the repository metadata alone does not show one. This is the single most important thing to verify before committing engineering time.
Where SecretFlow is the wrong tool
SecretFlow assumes you are willing to adopt its device model. If your problem is one narrow cryptographic operation, that model is overhead. A team that only needs private set intersection, or only needs homomorphic encryption primitives, is better served by a library that does that one thing and nothing else. The repository itself points to HEU for homomorphic encryption and SCQL for joint analysis among distrusting parties, both of which are narrower than the full framework. A second case: if your data is not partitioned at all and your concern is regulatory rather than cryptographic, no amount of device abstraction helps, because the framework's value comes from computing across parties who cannot share raw data. A third: the workflow layer integrates preprocessing, training and tuning, which is convenient when your pipeline matches its shape and constraining when it does not. There is also a documentation-language consideration. The README links a Simplified Chinese version first and the homepage is the .org.cn domain, so the primary documentation set may be more complete in Chinese than in English. That affects how quickly a non-Chinese-reading team can debug a device-level failure.
SCQL as the narrower alternative, and the actual difference
SCQL is the most instructive comparison because it comes from the same project family. The README describes it as "a system that allows multiple distrusting parties to run joint analysis without revealing their private data". The difference in approach is scope and interface. SCQL is a query system: parties express what they want as SQL against a joint schema, and the system handles the secure execution. SecretFlow is a programming framework: you write Python against device objects and a DAG, and you choose the partitioning and the protocol. If your analysts already think in SQL and your task is aggregate analysis rather than model training, SCQL removes an entire layer of abstraction you would otherwise have to learn. If you need to train a model, tune hyperparameters, and run the same code under different secret devices, SecretFlow's device layer is the thing SCQL does not offer. Choosing between them is really choosing whether your team's primary artifact is a query or a program.
Maintenance cost, upgrade cadence and licence
The release cadence visible here is roughly one beta per quarter, with v1.12.0b0 in April 2025, v1.13.0b0 in July 2025 and v1.14.0b0 in September 2025, and the repository shows a last push in April 2026. A quarterly beta line means upgrades arrive often enough that pinning a version and testing before each bump is part of the operating cost, not an afterthought. Because SecretFlow depends on sibling projects (Kuscia, SPU, HEU, YACL), an upgrade can require coordinating versions across that set rather than bumping one package. The licence is Apache-2.0, which is a permissive licence that permits commercial use and modification and includes an explicit patent grant; it also means you carry the obligation to preserve notices and state changes. That is a general description of the licence text, not legal advice, and if you are embedding this in a product you should have counsel read the Apache-2.0 terms alongside any dependency licences from the C++ components. The benchmarks are documented in OVERALL_BENCHMARK.md under docs/developer/benchmark/overall_benchmark.md rather than in the README, so performance expectations should be taken from that file and from the tutorials, not inferred from the architecture diagram.
Editorial conclusion
SecretFlow is aimed at teams that already know which privacy-enhancing technique their data split requires and want one Python surface for it. If you only need a single protocol, a narrower library such as HEU or SCQL is less machinery to carry. Before adopting, read INSTALLATION.md and DEPLOYMENT.md in docs/getting_started, confirm whether the v1.14.0b0 beta tag is acceptable for your environment, and check the OVERALL_BENCHMARK.md numbers against your own data scale.
Community notes