TenSEAL is a library for doing homomorphic encryption operations on tensors, built on top of Microsoft SEAL. It provides ease of use through a Python API, while preserving efficiency by implementing most of its operations using C++.
- 🔑 Encryption/Decryption of vectors of integers using BFV
- 🗝️ Encryption/Decryption of vectors of real numbers using CKKS
- 🔥 Element-wise addition, subtraction and multiplication of encrypted-encrypted vectors and encrypted-plain vectors
- 🌀 Dot product and vector-matrix multiplication
- 📊 N-dimensional encrypted tensors (
CKKSTensor,BFVTensor) with reshape, broadcast and transpose - 💾 Serialization of contexts, keys and encrypted tensors
- ⚡ Complete SEAL API under
tenseal.sealapi
We show the basic operations over encrypted data, more advanced usage for machine learning applications can be found on our tutorial section
TenSEAL is a binding over Microsoft SEAL plus a tensor layer on top, so the encryption parameters below (poly_modulus_degree, coeff_mod_bit_sizes, global_scale) carry exactly their SEAL meaning. Choosing them determines both the security level and how many operations you can chain before the noise budget is exhausted — see the SEAL documentation and its CKKS examples for what the values mean and how to pick them.
import tenseal as ts
# Setup TenSEAL context
context = ts.context(
ts.SCHEME_TYPE.CKKS,
poly_modulus_degree=8192,
coeff_mod_bit_sizes=[60, 40, 40, 60]
)
context.generate_galois_keys()
context.global_scale = 2**40
v1 = [0, 1, 2, 3, 4]
v2 = [4, 3, 2, 1, 0]
# encrypted vectors
enc_v1 = ts.ckks_vector(context, v1)
enc_v2 = ts.ckks_vector(context, v2)
result = enc_v1 + enc_v2
result.decrypt() # ~ [4, 4, 4, 4, 4]
result = enc_v1.dot(enc_v2)
result.decrypt() # ~ [10]
matrix = [
[73, 0.5, 8],
[81, -5, 66],
[-100, -78, -2],
[0, 9, 17],
[69, 11 , 10],
]
result = enc_v1.matmul(matrix)
result.decrypt() # ~ [157, -90, 153]TenSEAL requires Python 3.11 or newer and depends on NumPy.
pip install tensealPrebuilt wheels are published for every supported Python version on:
| Platform | Wheel |
|---|---|
| Linux, glibc (x86-64) | manylinux_2_28_x86_64 |
| Linux, musl (x86-64) | musllinux_1_2_x86_64 |
| Linux, glibc (aarch64) | manylinux_2_28_aarch64 |
| macOS (Apple Silicon) | macosx_14_0_arm64 |
| Windows (x64) | win_amd64 |
Linux wheels come in two flavours: manylinux for glibc-based distributions and
musllinux for musl-based ones such as Alpine, including the -alpine container
images. pip picks the right one for your platform automatically.
A source distribution is published as well, so pip install tenseal also works on platforms without a prebuilt wheel — it will compile from source, which needs the build requirements listed below. If your platform is missing a wheel you would like us to publish, please open an issue.
To check that the installation worked:
import tenseal as ts
print(ts.__version__)If your Python is older than 3.11, or you would rather leave your system Python alone, uv can download a Python for you and keep TenSEAL in its own environment.
Create an environment and install into it:
uv venv --python 3.13
source .venv/bin/activate # Windows: .venv\Scripts\activate
uv pip install tensealOr start a one-off Python session without setting anything up — uv fetches Python 3.13 and TenSEAL, and discards the environment afterwards:
uv run --python 3.13 --with tenseal pythonReplace 3.13 with any version from 3.11 to 3.14.
TenSEAL is not published on conda-forge, so install it with pip inside the environment:
conda create -n tenseal python=3.13
conda activate tenseal
pip install tensealBuilding requires a C++17 toolchain and CMake 3.14 or newer:
- Linux: GCC >= 7 or Clang >= 5
- macOS: Xcode 15.x command line tools
- Windows: Visual Studio 2017 or newer
All third-party dependencies — including Microsoft SEAL and Protocol Buffers — are fetched and built automatically by CMake. There is nothing to install by hand and no submodules to initialise.
pip install .Note: with CMake 4.0 or newer the build fails with
Compatibility with CMake < 3.5 has been removed, because some vendored dependencies still declare a pre-3.5 minimum. Until those are upgraded, setCMAKE_POLICY_VERSION_MINIMUM=3.5in your environment before building.
Note: on macOS, AppleClang 17 and newer (Xcode 16+) currently fail to compile the vendored xtensor. Use Xcode 15.x, or install the published wheel instead.
TODO: the images on Docker Hub are unmaintained — the newest was published in 2021 for v0.3.4, and both
openmined/tensealandopenmined/tenseal:devare far behind the current release. Thedocker-images/directory targets Python 3.6–3.9, all of which are end-of-life and below the supported minimum. Do not rely on these images. Refreshing or retiring them is tracked as future work.
TODO: the Bazel build is currently broken and its workflow runs on demand only. Its dependency pins have drifted from the CMake build, and it has not been migrated to bzlmod. Use the CMake build (
pip install .) in the meantime. Restoring Bazel support is tracked as future work.
Benchmark results from every merge to main are published on GitHub Pages, for Linux, macOS and Windows.
The benchmark suite runs with pytest:
pytest tests/python/benchmarks/TODO: the C++ microbenchmarks under
tests/cpp/benchmarks/are only wired up through Bazel, so they cannot currently be run. See the Bazel note above.
- Getting Started
- Tutorial 1 - Training and Evaluation of Logistic Regression on Encrypted Data
- Tutorial 2 - Working with Approximate Numbers
- Tutorial 3 - Benchmarks
- Tutorial 4 - Encrypted Convolution on MNIST
A. Benaissa, B. Retiat, B. Cebere, A.E. Belfedhal, "TenSEAL: A Library for Encrypted Tensor Operations Using Homomorphic Encryption", ICLR 2021 Workshop on Distributed and Private Machine Learning (DPML 2021).
@misc{tenseal2021,
title={TenSEAL: A Library for Encrypted Tensor Operations Using Homomorphic Encryption},
author={Ayoub Benaissa and Bilal Retiat and Bogdan Cebere and Alaa Eddine Belfedhal},
year={2021},
eprint={2104.03152},
archivePrefix={arXiv},
primaryClass={cs.CR}
}
For support in using this library, please join the #support Slack channel. Click here to join our Slack community!
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
See CONTRIBUTING.md for how to set up a development environment, build the library, and run the tests. Please make sure to update tests as appropriate.