keras-tcn: A Dilated Causal Conv1D Layer for Keras Sequence Models
Keras Temporal Convolutional Network. Supports Python and R.
At a glance
- What is it?
- keras-tcn packages the TCN architecture from Bai, Kolter and Koltun as a drop-in Keras layer. It is a good fit when you want a fixed receptive field, causal padding and parallel training, and a poor fit when you need streaming state or online inference.
- Who is it for?
- Adopt keras-tcn if you are training offline on sequences where the whole window is available at once and you want to tune the receptive field explicitly through the dilations list. Do not adopt it if your serving path needs to carry hidden state across calls, since the layer exposes no state object the way an LSTM does.
- Can I use it commercially?
- Yes. MIT 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 91 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 gap keras-tcn fills between Conv1D and LSTM
If you have a sequence modelling problem, the default Keras options are a stack of Conv1D layers or an LSTM/GRU. A plain Conv1D stack has a receptive field that grows linearly with depth, so covering a few hundred timesteps means either a very deep network or a large kernel. An LSTM covers arbitrary history in principle, but it processes timesteps one at a time, which limits parallelism during training, and the README points to vanishing gradients as a known issue with backpropagation through time. keras-tcn sits between these two. It is a convolutional layer, so the forward pass over a training batch is parallel across timesteps, but the dilation schedule lets a handful of layers span a long history. The README states that TCNs exhibit longer memory than recurrent architectures with the same capacity and that they perform better than LSTM/GRU on long time series, listing Seq. MNIST, the Adding Problem, Copy Memory and word-level PTB as the reference tasks. Those claims come from the paper the layer implements, not from measurements in this repository. The audience is anyone already inside Keras who wants a sequence layer with an explicit, tunable memory horizon rather than an implicit one.
Residual blocks, dilations and the receptive field arithmetic
The layer is built from residual blocks stacked on top of each other. The README states that a single ResidualBlock contains two Conv1d layers, which is why the factor of 2 appears in the receptive field formula. Each block applies a convolution with a dilation factor taken from the dilations tuple, adds its input back to its output, and passes the result through the activation. The default dilations are (1, 2, 4, 8, 16, 32), so six blocks, each doubling the spacing between sampled timesteps. nb_stacks repeats this whole block sequence, and the total receptive field is the sum over stacks of the per-stack span, with kernel_size K and the number of blocks per stack determining the width. The README gives the formula in an image rather than as text, so the exact expression cannot be quoted here, but the variables are named: N_stack for the number of stacks, N_b for the number of residual blocks per stack, d for the dilation vector, and K for the kernel size. Padding is causal by default, meaning a filter at time T only sees timesteps at or before T. That is the property that makes the layer usable for forecasting, where seeing the future would invalidate the result. The README is blunt about the failure mode: if you feed a sequence longer than the receptive field, the extra values further back are replaced with zeros. That is a silent information loss, not an error.
Choosing nb_filters, kernel_size and dilations from the README notes
The README includes tuning notes that read as practitioner experience rather than documentation. On nb_filters, the note is that more filters help until overfitting starts, and that the parameter plays a role similar to units in an LSTM. On kernel_size, the suggested range is 2 to 8, with 2 or 3 appropriate when the sequence depends mostly on the two immediately preceding timesteps, and larger kernels preferred for NLP. On dilations, the advice is to match the receptive field against the length of the features in your sequence, and to use multiples of the period if the input is periodic. nb_stacks is described as not very useful unless sequences are very long, with waveforms of hundreds of thousands of timesteps given as the example. use_skip_connections is recommended to stay on unless performance drops. For normalisation, the note says to use batch norm or layer norm when the network is large enough and there is enough data, with a stated personal preference for use_layer_norm. The activation note says the author has never changed it from the default relu. Read together, these notes narrow the search space considerably: kernel_size and dilations are the two knobs that matter most, and the rest are either defaults or conditional on scale.
Installing and wiring the layer into a model
Installation is a single command: pip install keras-tcn. MacOS users who want GPU support are pointed at pip install tensorflow-metal. The README states the code has been tested with TensorFlow 2.9 through 2.19, with the note dated March 13, 2025. The layer is constructed with keyword arguments, for example TCN(nb_filters=64, kernel_size=3, nb_stacks=1, dilations=(1, 2, 4, 8, 16, 32), padding='causal', use_skip_connections=True, dropout_rate=0.0, return_sequences=False, activation='relu', kernel_initializer='he_normal', use_batch_norm=False, use_layer_norm=False, go_backwards=False, return_state=False). Input is a 3D tensor of shape (batch_size, timesteps, input_dim). The timesteps dimension may be set to None, which the README notes is useful when sequences have different lengths, and points at tasks/multi_length_sequences.py as a worked example. Output is 3D of shape (batch_size, timesteps, nb_filters) when return_sequences is True, and 2D of shape (batch_size, nb_filters) when it is False. The kwargs pass through to the parent Keras Layer, and the README advises giving unique names when more than one TCN is used in a model. An R-language walkthrough is linked from issue 246 rather than maintained as a separate package.
Where the layer does not fit: state, streaming and long-horizon inputs
The clearest limitation is the one the README states outright: sequences longer than the receptive field get their older values zeroed out. If your application needs the model to attend to something 5,000 steps back and your dilations only span 500, no amount of training will recover that information. Increasing dilations or nb_stacks widens the field, but each added block costs parameters and compute, and the README's note on nb_stacks suggests the author considers stacking worthwhile only for very long sequences. A second limitation is architectural. go_backwards and return_state exist as arguments, and return_state is documented as returning the last state in addition to the output, but a convolutional layer has no recurrent hidden state to carry between calls. Anything that depends on incremental streaming inference, where you feed one timestep at a time and keep a running state, has to be handled by the surrounding framework rather than by this layer. If your serving path is request-per-timestep with persistent state, an LSTM or GRU remains the simpler choice. There is also a versioning signal worth reading: the last tagged release is 3.3.0 from February 2021, while the README's TensorFlow compatibility note is dated March 2025. That pattern suggests compatibility upkeep rather than feature development, and anyone expecting new layer options should check the commit history rather than the release list.
How this differs from Keras LSTM, GRU and a plain Conv1D stack
The nearest alternative inside Keras is the LSTM or GRU layer, and the difference is in how memory is represented. A recurrent layer carries a hidden vector forward through time and decides at each step what to keep, so its effective memory is learned and unbounded in principle. keras-tcn instead fixes the memory horizon at construction time through the dilation schedule. That is a trade: you give up the ability to learn which distant timesteps matter, and in exchange you get a horizon you can compute before training, a forward pass that parallelises across the time axis, and gradients that do not have to travel through a recurrence. The README frames this as stable gradients compared to backpropagation through time. Against a plain stack of Conv1D layers with padding='same', the difference is dilation. A Conv1D stack at kernel size 3 reaches 3 timesteps per layer; the default keras-tcn configuration reaches far further with six blocks. Against a WaveNet-style hand-rolled implementation, which is what the README's figure references, keras-tcn is the same idea packaged as a Keras Layer with the residual block, skip connections and normalisation options already wired. Choosing between them comes down to whether you want the memory horizon to be a hyperparameter you set or a property the model learns.
Licence, maintenance and what to check before you depend on it
The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. This is a permissive licence with no copyleft obligation on your own code, though anyone embedding it in a distributed product should read the full text rather than rely on that summary. On maintenance, the observable facts are these: the default branch is master, the repository is not archived, the last push recorded is June 2026, and the most recent tagged release is 3.3.0 from February 2021, described as a fix of the receptive field. Earlier releases cover weight normalization support and matching the original paper architecture. The gap between release tags and the README's TensorFlow 2.19 compatibility note is the thing to verify for your own environment: pin your TensorFlow version, install, and confirm the layer builds and trains on a small sequence before migrating a production model onto it. The README's own parameter notes are the best starting point for that test, since they tell you which arguments to vary first.
Editorial conclusion
Adopt keras-tcn if you are training offline on sequences where the whole window is available at once and you want to tune the receptive field explicitly through the dilations list. Do not adopt it if your serving path needs to carry hidden state across calls, since the layer exposes no state object the way an LSTM does. Before committing, verify the receptive field your configuration produces against your longest input sequence, because the documentation states that values further back than the receptive field are replaced with zeros.
Community notes