Installation | Documentation | Contributing | License

TorchCodec

TorchCodec is a PyTorch-native library for decoding and encoding media: videos, audio, and images, on CPU and CUDA GPU. It aims to be fast, easy to use, and well integrated into the PyTorch ecosystem. If you want to use PyTorch to train ML models on videos, audio, or images, or run inference, TorchCodec is how you turn these into tensors, and back.

We achieve these capabilities through:

Pythonic APIs that mirror Python and PyTorch conventions.
Relying on FFmpeg to do the video and audio decoding and encoding. TorchCodec uses the version of FFmpeg you already have installed. FFmpeg is a mature library with broad coverage available on most systems. It is, however, not easy to use. TorchCodec abstracts FFmpeg's complexity to ensure it is used correctly and efficiently. (FFmpeg is optional, and the image decoders and encoders don't need it: see Installing TorchCodec.)
Returning data as PyTorch tensors, ready to be fed into PyTorch transforms or used directly to train models.

Usage Examples

Below are some examples of what you can do with TorchCodec. For more detailed examples and more use-cases, check out our documentation!

Video Decoding

from torchcodec.decoders import VideoDecoder

device = "cpu"  # or e.g. "cuda" !
decoder = VideoDecoder("path/to/video.mp4", device=device)

decoder.metadata
# VideoStreamMetadata:
#   num_frames: 250
#   duration_seconds: 10.0
#   bit_rate: 31315.0
#   codec: h264
#   average_fps: 25.0
#   ... (truncated output)

# Simple Indexing API
decoder[0]  # uint8 tensor of shape [C, H, W]
decoder[0 : -1 : 20]  # uint8 stacked tensor of shape [N, C, H, W]

# Indexing, with PTS and duration info:
decoder.get_frames_at(indices=[2, 100])
# FrameBatch:
#   data (shape): torch.Size([2, 3, 270, 480])
#   pts_seconds: tensor([0.0667, 3.3367], dtype=torch.float64)
#   duration_seconds: tensor([0.0334, 0.0334], dtype=torch.float64)

# Time-based indexing with PTS and duration info
decoder.get_frames_played_at(seconds=[0.5, 10.4])
# FrameBatch:
#   data (shape): torch.Size([2, 3, 270, 480])
#   pts_seconds: tensor([ 0.4671, 10.3770], dtype=torch.float64)
#   duration_seconds: tensor([0.0334, 0.0334], dtype=torch.float64)

You can use the following snippet to generate a video with FFmpeg and try out the VideoDecoder:

ffmpeg -f lavfi -i testsrc2=size=640x400:duration=10:rate=25 /tmp/output_video.mp4

Video and Audio Encoding

from torchcodec.encoders import Encoder

encoder = Encoder()
video_stream = encoder.add_video(
    height=height, width=width, frame_rate=frame_rate,
)
audio_stream = encoder.add_audio(
    sample_rate=sample_rate, num_channels=num_channels,
)
with encoder.open_file("output.mp4"):
    video_stream.add_frames(frames_batch_0)
    audio_stream.add_samples(samples_batch_0)
    video_stream.add_frames(frames_batch_1)
    audio_stream.add_samples(samples_batch_1)
    # ...

Image Decoding and Encoding

from torchcodec.decoders import decode_image, decode_jpeg
from torchcodec.encoders import JpegEncoder

# JPEG, PNG, WebP, GIF, AVIF and HEIC, with the format detected automatically.
image = decode_image("path/to/image.jpg")  # uint8 tensor of shape [C, H, W]

# Or use the format-specific decoders, e.g. to decode JPEGs on GPU:
image = decode_jpeg("path/to/image.jpg", device="cuda")

# JPEG and PNG encoding. JPEGEncoder also supports CUDA encoding!
JpegEncoder(image).to_file("output.jpg")  # also .to_tensor() and .to_file_like()

Installing TorchCodec

Install FFmpeg, if it's not already installed. TorchCodec supports all major FFmpeg versions in [4, 9]. Linux distributions usually come with FFmpeg pre-installed. You'll need FFmpeg that comes with separate shared libraries. This is especially relevant for Windows users: these are usually called the "shared" releases.

If FFmpeg is not already installed, or you need a more recent version, an easy way to install it is to use conda:
```
conda install "ffmpeg"
# or
conda install "ffmpeg" -c conda-forge
```
Note: FFmpeg is an optional dependency. It is needed for video and audio decoding and encoding (VideoDecoder, AudioDecoder, VideoEncoder, AudioEncoder, etc.). The image decoders and encoders (decode_image, decode_jpeg, JpegEncoder, PngEncoder, etc.) do not require FFmpeg, so if you only need images you can skip this step.
Install PyTorch and TorchCodec:
```
pip install torch torchcodec
```
That's it! On Linux x86 and aarch64, this will install CUDA-enabled wheels by default (matching the default behavior of pip install torch). These wheels should still work even if you do not have a GPU on your machine. On macOS and Windows this will install CPU-only wheels. CPU wheels are available for Linux (x86_64 and aarch64), macOS, and Windows.

CUDA support

On CUDA GPUs, TorchCodec supports decoding and encoding of videos and jpeg images. CUDA-enabled wheels are installed by default on Linux. For Windows, you'll need to pass --index-url as described below.

For video, make sure you have a GPU with NVDEC and NVENC hardware that supports the formats you want. Refer to Nvidia's GPU support matrix here.

To select a specific CUDA Toolkit version, use --index-url. Make sure to install the corresponding PyTorch version as well (refer to the official instructions):

# This corresponds to CUDA Toolkit version 13.0.
pip install torch torchcodec --index-url=https://download.pytorch.org/whl/cu130

Make sure your FFmpeg has NVDEC and NVENC support:

ffmpeg -decoders | grep -i nvidia
# This should show a line like this:
# V..... h264_cuvid           Nvidia CUVID H264 decoder (codec h264)

ffmpeg -encoders | grep -i nvidia
# This should show a line like this:
# V....D h264_nvenc           NVIDIA NVENC H.264 encoder (codec h264)

To check that FFmpeg libraries work with NVDEC correctly you can decode a generated test video:

ffmpeg -hwaccel cuda -hwaccel_output_format cuda -f lavfi -i testsrc2=duration=1 -f null -

CPU-only installation

To install CPU-only wheels explicitly (e.g. on Linux where CUDA wheels are the default):

pip install torchcodec --index-url=https://download.pytorch.org/whl/cpu

XPU support

Intel GPUs (XPU) support requires a stand-alone plugin for TorchCodec:

pip install torchcodec-xpu --extra-index-url=https://download.pytorch.org/whl/xpu

For any XPU-related support, please refer to https://github.com/intel/torchlib-xpu.

Compatibility with `torch` versions

The following table indicates the compatibility between versions of torchcodec, torch and Python.

`torchcodec`	`torch`	Python
`main` / `nightly`	`main` / `nightly`	`>=3.10`, `<=3.14`
`0.15`	`>=2.11`	`>=3.10`, `<=3.14`
`0.14`	`>=2.11`	`>=3.10`, `<=3.14`
`0.13`	`>=2.11`	`>=3.10`, `<=3.14`

older versions

`torchcodec`	`torch`	Python
`0.12`	`>=2.11`	`>=3.10`, `<=3.14`
`0.11`	`2.11`	`>=3.10`, `<=3.14`
`0.10`	`2.10`	`>=3.10`, `<=3.14`
`0.9`	`2.9`	`>=3.10`, `<=3.14`
`0.8`	`2.9`	`>=3.10`, `<=3.13`
`0.7`	`2.8`	`>=3.9`, `<=3.13`
`0.6`	`2.8`	`>=3.9`, `<=3.13`
`0.5`	`2.7`	`>=3.9`, `<=3.13`
`0.4`	`2.7`	`>=3.9`, `<=3.13`
`0.3`	`2.7`	`>=3.9`, `<=3.13`
`0.2`	`2.6`	`>=3.9`, `<=3.13`
`0.1`	`2.5`	`>=3.9`, `<=3.12`
`0.0.3`	`2.4`	`>=3.8`, `<=3.12`

Contributing

We welcome contributions to TorchCodec! Please see our contributing guide for more details.

License

TorchCodec is released under the BSD 3 license.

However, TorchCodec may be used with code not written by Meta which may be distributed under different licenses.

For example, if you build TorchCodec with ENABLE_CUDA=1 or use the CUDA-enabled release of torchcodec, please review CUDA's license here: Nvidia licenses.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

torchcodec-0.16.0-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (9.5 MB view details)

Uploaded Aug 13, 2026 CPython 3.14tmanylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

torchcodec-0.16.0-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl (8.4 MB view details)

Uploaded Aug 13, 2026 CPython 3.14tmanylinux: glibc 2.27+ ARM64manylinux: glibc 2.28+ ARM64

torchcodec-0.16.0-cp314-cp314t-macosx_14_0_arm64.whl (3.9 MB view details)

Uploaded Aug 13, 2026 CPython 3.14tmacOS 14.0+ ARM64

torchcodec-0.16.0-cp314-cp314-win_amd64.whl (6.4 MB view details)

Uploaded Aug 13, 2026 CPython 3.14Windows x86-64

torchcodec-0.16.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (9.5 MB view details)

Uploaded Aug 13, 2026 CPython 3.14manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

torchcodec-0.16.0-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl (8.4 MB view details)

Uploaded Aug 13, 2026 CPython 3.14manylinux: glibc 2.27+ ARM64manylinux: glibc 2.28+ ARM64

torchcodec-0.16.0-cp314-cp314-macosx_14_0_arm64.whl (3.9 MB view details)

Uploaded Aug 13, 2026 CPython 3.14macOS 14.0+ ARM64

torchcodec-0.16.0-cp313-cp313-win_amd64.whl (6.4 MB view details)

Uploaded Aug 13, 2026 CPython 3.13Windows x86-64

torchcodec-0.16.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (9.5 MB view details)

Uploaded Aug 13, 2026 CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

torchcodec-0.16.0-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl (8.4 MB view details)

Uploaded Aug 13, 2026 CPython 3.13manylinux: glibc 2.27+ ARM64manylinux: glibc 2.28+ ARM64

torchcodec-0.16.0-cp313-cp313-macosx_14_0_arm64.whl (3.9 MB view details)

Uploaded Aug 13, 2026 CPython 3.13macOS 14.0+ ARM64

torchcodec-0.16.0-cp312-cp312-win_amd64.whl (6.4 MB view details)

Uploaded Aug 13, 2026 CPython 3.12Windows x86-64

torchcodec-0.16.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (9.5 MB view details)

Uploaded Aug 13, 2026 CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

torchcodec-0.16.0-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl (8.4 MB view details)

Uploaded Aug 13, 2026 CPython 3.12manylinux: glibc 2.27+ ARM64manylinux: glibc 2.28+ ARM64

torchcodec-0.16.0-cp312-cp312-macosx_14_0_arm64.whl (3.9 MB view details)

Uploaded Aug 13, 2026 CPython 3.12macOS 14.0+ ARM64

torchcodec-0.16.0-cp311-cp311-win_amd64.whl (6.4 MB view details)

Uploaded Aug 13, 2026 CPython 3.11Windows x86-64

torchcodec-0.16.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (9.5 MB view details)

Uploaded Aug 13, 2026 CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

torchcodec-0.16.0-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl (8.4 MB view details)

Uploaded Aug 13, 2026 CPython 3.11manylinux: glibc 2.27+ ARM64manylinux: glibc 2.28+ ARM64

torchcodec-0.16.0-cp311-cp311-macosx_14_0_arm64.whl (3.9 MB view details)

Uploaded Aug 13, 2026 CPython 3.11macOS 14.0+ ARM64

torchcodec-0.16.0-cp310-cp310-win_amd64.whl (6.4 MB view details)

Uploaded Aug 13, 2026 CPython 3.10Windows x86-64

torchcodec-0.16.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (9.5 MB view details)

Uploaded Aug 13, 2026 CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

torchcodec-0.16.0-cp310-cp310-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl (8.4 MB view details)

Uploaded Aug 13, 2026 CPython 3.10manylinux: glibc 2.27+ ARM64manylinux: glibc 2.28+ ARM64

torchcodec-0.16.0-cp310-cp310-macosx_14_0_arm64.whl (3.9 MB view details)

Uploaded Aug 13, 2026 CPython 3.10macOS 14.0+ ARM64

File details

Details for the file torchcodec-0.16.0-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

Download URL: torchcodec-0.16.0-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Upload date: Aug 13, 2026
Size: 9.5 MB
Tags: CPython 3.14t, manylinux: glibc 2.27+ x86-64, manylinux: glibc 2.28+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for torchcodec-0.16.0-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`a273d93170813d6aabb8e6a5366bd4e337ad2ea2d9b07226cca60f0165895945`
MD5	`1ca355bbfbbb315733382d1ae55b7cce`
BLAKE2b-256	`ecdb3028851cb7e349b2c785b0c6423803031409d1a6fd6e9e029055503ec833`

Algorithm	Hash digest
SHA256	`f867dadd3520d0a098bcdcb1a7f23ee99d3fccc4ba3a82f27d5228330e2f41d9`
MD5	`00b2481ef5b4ef9c50f1907782032408`
BLAKE2b-256	`9881a8830cb62a29fb4d4eb7793919f56b7b420c0ce27b5683e09d9b75b8c28f`

Algorithm	Hash digest
SHA256	`6b28fd96c904f157ee43c417c5d9fdc1a6f5709b3039fa85e0fa943004c9439c`
MD5	`33d9e1bfb5b30eb324c9e19909ac7522`
BLAKE2b-256	`4520c713f33e492e819979322dab56f2807208f0554f92d3f96caa9dd7cf6bef`

Algorithm	Hash digest
SHA256	`602a5d8fa1c26d52d3c814e8912ab3a5538889f1384665260061addef2b5d83c`
MD5	`1e9b54ec917d7db3256d06cc7bbb991c`
BLAKE2b-256	`187455fd918f3a1a3b1bcb77d7239ae44cd302e2140c94378fa436691e08e548`

Algorithm	Hash digest
SHA256	`12bd2c7eff4056e74c1f57c115d455a5efc2d0f577517242ec66bf30712f5a9f`
MD5	`5411a8540b3310b4cbde2e6f7ae963df`
BLAKE2b-256	`1c5807df4dc91580bc878eaf6f0b9b43c0823f67fb3a926e816c6869494b0710`

Algorithm	Hash digest
SHA256	`d2e2742562569eb88230c27570de1116ac361026202447371d9c52dcac324ad4`
MD5	`389383fd5c92d15d58f8cd0a5a75d19d`
BLAKE2b-256	`1ad28769570eeadc4fd66f2638f16d8a48b5266f3458d0d5fb11bb29cc38d1c5`

Algorithm	Hash digest
SHA256	`9fcda10720fcbccae8744b8581080e985f7743cb8b365f7ce2bb6f045e7b84fd`
MD5	`44219d4cfa0157caea16cd45a3d77a3a`
BLAKE2b-256	`aaaeba8a4fcc5af759006c156bae38d12aa6bf9635742a8f8175f33ebe37b50e`

Algorithm	Hash digest
SHA256	`158e1ed469a5300aeb843102f8d6c4354f97a835ce5dca087aa827c135bd4869`
MD5	`dccaac8ce671e1d30058f454ab39a261`
BLAKE2b-256	`38760551e83bb23731806d98469cc8cdc887d55c3a242d7377a52430aa2cd6bf`

Algorithm	Hash digest
SHA256	`26f4c4ee2896ddee5b38bf31ae96e721b853dba6b0b4104ac2e11391ddd7966d`
MD5	`0f7024339bdd210bf7cb007ef0d6befe`
BLAKE2b-256	`411c9b12cfd462ff2a7cbad52907de9dd1963bca7aa4bf6a4e2d618195af7275`

Algorithm	Hash digest
SHA256	`d14e43ace5f9fe095287a5b4a39f1c4353c01493749e40ff4e17ebb791f741e8`
MD5	`7304e4dbaaef2090ba83798c1aacb622`
BLAKE2b-256	`b6837844821bd5d0a1d8bee0568d417d2b3f0663f379666edd22348f0f90e427`

Algorithm	Hash digest
SHA256	`154c5cf6c2dd2801700dcf0939081f614c50dcbf99f5ecc7f6854e98b7959339`
MD5	`16ae96e5a0888818ffac69bf159cefc3`
BLAKE2b-256	`a06259ef3c1f377a08ca965cf71abd763db5cbf8f6a97901ca09dbe0809c4a29`

Algorithm	Hash digest
SHA256	`d9e4c83b3c02b206b24a5409746babd74ed00bfa0a6320b23714d73c61124397`
MD5	`ecbdbe85f906b081320bc72de9233607`
BLAKE2b-256	`0f7700f106e48bc20d9e3e72e85077849eabc3a5ae9839ce0df961d48424747d`

Algorithm	Hash digest
SHA256	`5309c29e31b719f81dba75fcfa49a9ce6a38d069d7f570767466fe634783e7ba`
MD5	`d64a7f4741f1d4d488e5e917677375d0`
BLAKE2b-256	`ca5b2a15225d77fc2ef857bd290a98f1de99f0db03e104f93ce3af7bea704f4a`

Algorithm	Hash digest
SHA256	`d26fe96259211115c17fb2bd071fbdf4da264cf04bb88fba006ffffb9c23c5a1`
MD5	`8133976ea91e7c507f0b166b05a072e3`
BLAKE2b-256	`4eb744004280d1e80c492af54d2d94332834091bc59e211827cfc0232aca03a3`

Algorithm	Hash digest
SHA256	`9a899bf100cc40a0401fafc14f47c79979311d1df3fbe418c5d1019cde69d607`
MD5	`2469b0b3411c37f7c414e2e40c81bff0`
BLAKE2b-256	`d7b9d1780a0f5e3b4bcddec36e865ddec73b31047cf4fa8456e96c9f91852b12`

Algorithm	Hash digest
SHA256	`b44990348cb23d94c5455d3d9b4006bd58ba19a6e40d1e9bc02ff62ae070ae0e`
MD5	`f971a4aab35901e7271ad3bcee21b43c`
BLAKE2b-256	`8dadbec3e203b8e34ee542fd84c07e252a38cae70f7e2dccf0fa4f065dd6f34e`

Algorithm	Hash digest
SHA256	`1021a918c24184a1ce0b1dd8ca06408fe09ba988ecdaffc53b9dd51a42138ff0`
MD5	`fb6f13cf7d4b3f8094ae680c6fcb46c1`
BLAKE2b-256	`958ff9b71bac4d94686d5dd9c55530dc0ffb16a73b2f6a58ed03be52a1063952`

Algorithm	Hash digest
SHA256	`2f2111c9c2b4a76676ea265ffed3eac6031db386ced3b71ff6910cd31b1f4f1a`
MD5	`9ba00e9a7da707ee1c92d3ec23fb54bf`
BLAKE2b-256	`ca5dd16eeeb67f6407ad8b4b4254a7fd887f20c6080e462a2d5ad7f29730fc5e`

Algorithm	Hash digest
SHA256	`fd732bf687e74ba1b1b273bb272038664bb9c13a0b1747a25b604a7876613a5d`
MD5	`b39f0fad3f7296310ad8a2a698a71d7d`
BLAKE2b-256	`1c9337ea920f9c7c959ce87bf70ae65915a99ea7b8203cf0f996df9fe33bf2c0`

Algorithm	Hash digest
SHA256	`0db3218a1bbab542aa3d820899895eb3df17346846a25dc2b9f28c92c47e5998`
MD5	`df20e1b07761d70fd0bcad3ccbdeef50`
BLAKE2b-256	`003880819d6d29594e0ea1ade0aa7245dc7f690310b5d433a0a4c3d9256dad9d`

Algorithm	Hash digest
SHA256	`74862359c18950be2ece0368d2cd2b619901b3bc9b72e17272d116366d6ef92c`
MD5	`0295d0e1c3c662b6985a99aebfb6cb97`
BLAKE2b-256	`b497fde2b19565451a26f42ce02f386b950e39e007fbf3df49c60cc0f01b28b4`

torchcodec 0.16.0

TorchCodec

Usage Examples

Video Decoding

Video and Audio Encoding

Image Decoding and Encoding

Installing TorchCodec

CUDA support

CPU-only installation

XPU support

Compatibility with torch versions

Contributing

License

Project links

Key dates

5 maintainers

Credits

Requires

Provides Extra

Download files

Source Distributions

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

Compatibility with `torch` versions

Algorithm	Hash digest
SHA256	`4d2eddb85554cf1113935f706cb4f990d2cafc084aca6fbdea894a29d34d1c32`
MD5	`6e382fb8a1ba1fbb5f6715f10af5e699`
BLAKE2b-256	`2ee3177cc1dee2058ac7ae7ab218e8a7b088153ef0431e6293f1e416d3dd13c5`

Algorithm	Hash digest
SHA256	`b37783d709cb60694fe10ac03a7c2e78afdbe4cfcde5ea3f7d55a17ca23dafcd`
MD5	`158392438817dd35e5e37498d0f1976f`
BLAKE2b-256	`46e8ee512c4b803d22e205d425b601e23451882fa6db102a4514e6805c2d5b10`