Build | Status |
---|---|
Ubuntu/macOS | |
Ubuntu GPU custom ops |
TensorFlow Addons is a repository of contributions that conform to well-established API patterns, but implement new functionality not available in core TensorFlow. TensorFlow natively supports a large number of operators, layers, metrics, losses, and optimizers. However, in a fast moving field like ML, there are many interesting new developments that cannot be integrated into core TensorFlow (because their broad applicability is not yet clear, or it is mostly used by a smaller subset of the community).
The maintainers of TensorFlow Addons can be found in the CODEOWNERS file of the repo. This file is parsed and pull requests will automatically tag the owners using a bot. If you would like to maintain something, please feel free to submit a PR. We encourage multiple owners for all submodules.
TensorFlow Addons is available on PyPI for Linux & macOS (Windows support was dropped due to inconsistent TF2.15 whl packaging). To install the latest version, run the following:
pip install tensorflow-addons
To ensure you have a version of TensorFlow that is compatible with TensorFlow Addons,
you can specify the tensorflow
extra requirement during install:
pip install tensorflow-addons[tensorflow]
Similar extras exist for the tensorflow-gpu
and tensorflow-cpu
packages.
To use TensorFlow Addons:
import tensorflow as tf
import tensorflow_addons as tfa
TensorFlow Addons is actively working towards forward compatibility with TensorFlow 2.x.
However, there are still a few private API uses within the repository so at the moment
we can only guarantee compatibility with the TensorFlow versions which it was tested against.
Warnings will be emitted when importing tensorflow_addons
if your TensorFlow version does not match
what it was tested against.
TensorFlow Addons | TensorFlow | Python |
---|---|---|
tfa-nightly | 2.12, 2.13, 2.14 | 3.9, 3.10, 3.11 |
tensorflow-addons-0.22.0 | 2.12, 2.13, 2.14 | 3.9, 3.10, 3.11 |
tensorflow-addons-0.21.0 | 2.11, 2.12, 2.13 | 3.8, 3.9, 3.10, 3.11 |
tensorflow-addons-0.20.0 | 2.10, 2.11, 2.12 | 3.8, 3.9, 3.10, 3.11 |
tensorflow-addons-0.19.0 | 2.9, 2.10, 2.11 | 3.7, 3.8, 3.9, 3.10 |
tensorflow-addons-0.18.0 | 2.8, 2.9, 2.10 | 3.7, 3.8, 3.9, 3.10 |
tensorflow-addons-0.17.1 | 2.7, 2.8, 2.9 | 3.7, 3.8, 3.9, 3.10 |
tensorflow-addons-0.16.1 | 2.6, 2.7, 2.8 | 3.7, 3.8, 3.9, 3.10 |
tensorflow-addons-0.15.0 | 2.5, 2.6, 2.7 | 3.7, 3.8, 3.9 |
tensorflow-addons-0.14.0 | 2.4, 2.5, 2.6 | 3.6, 3.7, 3.8, 3.9 |
tensorflow-addons-0.13.0 | 2.3, 2.4, 2.5 | 3.6, 3.7, 3.8, 3.9 |
tensorflow-addons-0.12.1 | 2.3, 2.4 | 3.6, 3.7, 3.8 |
tensorflow-addons-0.11.2 | 2.2, 2.3 | 3.5, 3.6, 3.7, 3.8 |
tensorflow-addons-0.10.0 | 2.2 | 3.5, 3.6, 3.7, 3.8 |
tensorflow-addons-0.9.1 | 2.1, 2.2 | 3.5, 3.6, 3.7 |
tensorflow-addons-0.8.3 | 2.1 | 3.5, 3.6, 3.7 |
tensorflow-addons-0.7.1 | 2.1 | 2.7, 3.5, 3.6, 3.7 |
tensorflow-addons-0.6.0 | 2.0 | 2.7, 3.5, 3.6, 3.7 |
TensorFlow C++ APIs are not stable and thus we can only guarantee compatibility with the version TensorFlow Addons was built against. It is possible custom ops will work with multiple versions of TensorFlow, but there is also a chance for segmentation faults or other problematic crashes. Warnings will be emitted when loading a custom op if your TensorFlow version does not match what it was built against.
Additionally, custom ops registration does not have a stable ABI interface so it is
required that users have a compatible installation of TensorFlow even if the versions
match what we had built against. A simplification of this is that TensorFlow Addons
custom ops will work with pip
-installed TensorFlow but will have issues when TensorFlow
is compiled differently. A typical example of this would be conda
-installed TensorFlow.
RFC #133 aims to fix this.
TensorFlow Addons | TensorFlow | Compiler | cuDNN | CUDA |
---|---|---|---|---|
tfa-nightly | 2.14 | GCC 9.3.1 | 8.6 | 11.8 |
tensorflow-addons-0.22.0 | 2.14 | GCC 9.3.1 | 8.6 | 11.8 |
tensorflow-addons-0.21.0 | 2.13 | GCC 9.3.1 | 8.6 | 11.8 |
tensorflow-addons-0.20.0 | 2.12 | GCC 9.3.1 | 8.6 | 11.8 |
tensorflow-addons-0.19.0 | 2.11 | GCC 9.3.1 | 8.1 | 11.2 |
tensorflow-addons-0.18.0 | 2.10 | GCC 9.3.1 | 8.1 | 11.2 |
tensorflow-addons-0.17.1 | 2.9 | GCC 9.3.1 | 8.1 | 11.2 |
tensorflow-addons-0.16.1 | 2.8 | GCC 7.3.1 | 8.1 | 11.2 |
tensorflow-addons-0.15.0 | 2.7 | GCC 7.3.1 | 8.1 | 11.2 |
tensorflow-addons-0.14.0 | 2.6 | GCC 7.3.1 | 8.1 | 11.2 |
tensorflow-addons-0.13.0 | 2.5 | GCC 7.3.1 | 8.1 | 11.2 |
tensorflow-addons-0.12.1 | 2.4 | GCC 7.3.1 | 8.0 | 11.0 |
tensorflow-addons-0.11.2 | 2.3 | GCC 7.3.1 | 7.6 | 10.1 |
tensorflow-addons-0.10.0 | 2.2 | GCC 7.3.1 | 7.6 | 10.1 |
tensorflow-addons-0.9.1 | 2.1 | GCC 7.3.1 | 7.6 | 10.1 |
tensorflow-addons-0.8.3 | 2.1 | GCC 7.3.1 | 7.6 | 10.1 |
tensorflow-addons-0.7.1 | 2.1 | GCC 7.3.1 | 7.6 | 10.1 |
tensorflow-addons-0.6.0 | 2.0 | GCC 7.3.1 | 7.4 | 10.0 |
There are also nightly builds of TensorFlow Addons under the pip package
tfa-nightly
, which is built against the latest stable version of TensorFlow. Nightly builds
include newer features, but may be less stable than the versioned releases. Contrary to
what the name implies, nightly builds are not released every night, but at every commit
of the master branch. 0.9.0.dev20200306094440
means that the commit time was
2020/03/06 at 09:44:40 Coordinated Universal Time.
pip install tfa-nightly
You can also install from source. This requires the Bazel build system (version >= 1.0.0).
git clone https://github.com/tensorflow/addons.git
cd addons
# This script links project with TensorFlow dependency
python3 ./configure.py
bazel build build_pip_pkg
bazel-bin/build_pip_pkg artifacts
pip install artifacts/tensorflow_addons-*.whl
git clone https://github.com/tensorflow/addons.git
cd addons
export TF_NEED_CUDA="1"
# Set these if the below defaults are different on your system
export TF_CUDA_VERSION="12"
export TF_CUDNN_VERSION="8"
export CUDA_TOOLKIT_PATH="/usr/local/cuda"
export CUDNN_INSTALL_PATH="/usr/lib/x86_64-linux-gnu"
# This script links project with TensorFlow dependency
python3 ./configure.py
bazel build build_pip_pkg
bazel-bin/build_pip_pkg artifacts
pip install artifacts/tensorflow_addons-*.whl
See docs/tutorials/
for end-to-end examples of various addons.
User experience and project maintainability are core concepts in TensorFlow Addons. In order to achieve these we require that our additions conform to established API patterns seen in core TensorFlow.
TensorFlow Addons supports precompiled custom ops for CPU and GPU. However, GPU custom ops currently only work on Linux distributions. For this reason Windows and macOS will fallback to pure TensorFlow Python implementations whenever possible.
The order of priority on macOS/Windows is: 1) Pure TensorFlow + Python implementation (works on CPU and GPU) 2) C++ implementation for CPU
The order of priority on Linux is: 1) CUDA implementation 2) C++ implementation 3) Pure TensorFlow + Python implementation (works on CPU and GPU)
If you want to change the default priority, "C++ and CUDA" VS "pure TensorFlow Python",
you can set the environment variable TF_ADDONS_PY_OPS=1
from the command line or
run tfa.options.disable_custom_kernel()
in your code.
For example, if you are on Linux and you have compatibility problems with the compiled ops, you can give priority to the Python implementations:
From the command line:
export TF_ADDONS_PY_OPS=1
or in your code:
import tensorflow_addons as tfa
tfa.options.disable_custom_kernel()
This variable defaults to True
on Windows and macOS, and False
on Linux.
TensorFlow Addons has been designed to compartmentalize submodules so that they can be maintained by community users who have expertise, and a vested interest in that component. We heavily encourage users to submit sign up to maintain a submodule by submitting your username to the CODEOWNERS file.
Full write access will only be granted after substantial contribution has been made in order to limit the number of users with write permission. Contributions can come in the form of issue closings, bug fixes, documentation, new code, or optimizing existing code. Submodule maintainership can be granted with a lower barrier for entry as this will not include write permissions to the repo.
For more information see the RFC on this topic.
Given the nature of this repository, submodules may become less and less useful to the community as time goes on. In order to keep the repository sustainable, we'll be performing bi-annual reviews of our code to ensure everything still belongs within the repo. Contributing factors to this review will be:
Functionality within TensorFlow Addons can be categorized into three groups:
The status change between these three groups is: Suggested <-> Discouraged -> Deprecated.
The period between an API being marked as deprecated and being deleted will be 90 days. The rationale being:
In the event that TensorFlow Addons releases monthly, there will be 2-3 releases before an API is deleted. The release notes could give user enough warning.
90 days gives maintainers ample time to fix their code.
TensorFlow Addons is a community-led open source project (only a few maintainers work for Google!). As such, the project depends on public contributions, bug fixes, and documentation. This project adheres to TensorFlow's code of conduct. By participating, you are expected to uphold this code.
Do you want to contribute but are not sure of what? Here are a few suggestions:
docs/tutorials/
,
these are a great way to familiarize yourself and others with TensorFlow Addons. See
the guidelines for more information on how to add
examples.Please see contribution guidelines to get started (and remember, if you don't understand something, open an issue, or even make a pull request to improve the guide!).