FastLED WASM Compiler
| Build | Lint | Unit Test | Integration Test | |
|---|---|---|---|---|
| Linux x86 |  |
 |
 |
 |
| Linux ARM |  |
 |
 |
 |
| Windows x86 |  |
 |
 |
 |
| Windows ARM |  |
 |
 |
 |
| macOS x86 |  |
 |
 |
 |
| macOS ARM |  |
 |
 |
 |
Compile your FastLED sketch and run it on the browser!
Demo
https://zackees.github.io/fastled-wasm/
About
Compile FastLED sketches to browser-ready html/js/wasm output using a native Emscripten toolchain.
Compile times are extremely fast thanks to aggressive object caching and sketch fingerprinting. Recompilation of sketch files with minimal changes completes in under a second.
Tutorial Video
Note: This video predates the Rust CLI migration. Install with
pip install fastledand run withfastled mysketchfolder.
https://github.com/user-attachments/assets/64ae0e6c-5f8b-4830-ab87-dcc25bc61218
Install
pip install fastled
Alternative installers:
uv pip install fastled --systempipx install fastled
Executables
Pre-built binaries are published on each GitHub release:
Ubuntu Install Script
curl -L https://raw.githubusercontent.com/zackees/fastled-wasm/refs/heads/main/install_linux.sh | /bin/bash
Run
Change into a sketch directory and run:
fastled
Useful flags:
| Flag | Description |
|---|---|
--just-compile |
Compile and exit without opening a browser or watching files |
--no-app |
Emit the JavaScript API/WASM artifacts without the default index.js application |
| `--link <static | dynamic>` |
--debug |
Build with debug-friendly compiler settings |
--quick |
Default build mode |
--release |
Optimized build (~1/3 smaller binary) |
--fastled-path <path> |
Point the build at a local FastLED checkout |
--purge |
Clear cached FastLED downloads and stale WASM build artifacts |
--serve-dir <dir> |
Serve an existing directory without compiling |
Set FASTLED_VIEWER_LOGS=1 to forward the viewer window's browser console output (console.*, uncaught errors, failed fetches) to the terminal's stderr, prefixed with [viewer] — useful when diagnosing a blank or broken viewer.
Testing your sketch from CI or an agent
The shipped viewer can render a sketch, capture its canvas, collect browser logs, and exit without Playwright or a separate browser installation:
fastled examples/Blink --test --test-wait-secs=2 \
--test-screenshot=out/blink.png --test-log=out/blink.viewer.log \
--test-exit-on-error
For a frame sequence, add
--test-interval-secs=0.5 --test-count=10 and use a path such as
out/blink-{n:03}.png. The interval is the target between scheduled capture
starts; slow canvas readback or uploads can delay later frames. The wait begins
only after the compiled page has a canvas and two animation frames have
elapsed. Exit codes are 0 for success,
1 for compile/viewer/I/O failure, 2 for a captured page error when
--test-exit-on-error is enabled, 124 for the total timeout, and 125 for
the ready timeout. An interrupted run exits 130. The viewer and local server
are stopped automatically.
To run trusted host checks after the first rendered frame, repeat
--test-cmd options. They execute sequentially from the sketch directory,
and the test succeeds only after both the viewer schedule and all commands
finish:
fastled examples/Blink --test --test-log=out/run.log \
--test-cmd="python scripts/check_ready.py" \
--test-cmd="python scripts/check_runtime_state.py"
Commands use /bin/sh -c on Unix and %COMSPEC% /D /S /C (normally
cmd.exe) on Windows, with null stdin and no extra console window. Pipes,
redirection, &&, and quoting follow the platform shell; invoke
powershell -NoProfile -Command ... explicitly for PowerShell syntax.
Command stdout and stderr are drained and mirrored to the terminal. With
--test-log, timestamped stream markers are appended, such as
[fastled-test-cmd 0 stdout] ... and [fastled-test-cmd 0] exit=0.
Commands are trusted input and inherit the user's environment and filesystem
permissions. A spawn failure or nonzero command exit returns 1; the total
timeout (124) and interrupt (130) also terminate the active command and
its descendants.
Features
Browser Compatibility
Safari is a required production target. Release builds must not depend on Emscripten's JavaScript Promise Integration (JSPI), including -sJSPI, WebAssembly.Suspending, or WebAssembly.promising. Emscripten upgrades must preserve a non-JSPI async path and pass a real Safari smoke test before becoming the default toolchain.
Hot Reload
Once launched, the compiler remains open and watches for file changes. Edits to your sketch are automatically recompiled and the browser reloads with the updated output. Build output is streamed to the browser in real time via SSE.
Hot Reload FastLED Source
If you launch fastled inside the FastLED repo with --fastled-path, changes to the library source code are detected and trigger recompilation. Unlike sketch-only rebuilds, modifying a header file may produce a longer recompile.
Big Data in /data Directory
Large files (e.g. video) in a sketch's data/ directory are handled specially to avoid round-tripping blobs. The WASM compiler generates a sketch_assets.json manifest for an emulated SD card system mounted at /data/. Files named *.json, *.csv, *.txt are injected before setup() runs; all others are streamed asynchronously at runtime. The loader accepts legacy files.json output when running an older generated sketch.
For an example see examples/SdCard in the FastLED repo.
Compile Speed
Three compile modes are available: --quick (default), --release (optimized for size, ~1/3 smaller binary), and --debug (debug-friendly compiler settings). Aggressive object caching means incremental rebuilds are near-instant.
Arduino Compatibility
Most simple Arduino sketches compile out of the box. Common functions like digitalWrite(), Serial.println(), and others are stubbed. digitalRead() returns 0 and analogRead() returns random numbers.
HTTPS
The local preview server supports HTTPS using the bundled localhost certificate pair. HTTPS is required for browser features such as microphone access. See HTTPS_SSL.md.
Python Package
The fastled Python package is a compatibility launcher for the native Rust
CLI. Internal build, project discovery, and fuzzy matching behavior lives in
Rust and is tested there.
FAQs
Q: Why does FastLED become choppy when the browser tab is in the background? A: FastLED WASM currently runs on the main thread. Chrome throttles the event loop for background tabs. Moving to a Web Worker would solve this.
Q: Why does a long delay() freeze the browser?
A: delay() blocks loop() which blocks the main thread. A Web Worker would decouple FastLED from the browser's UI thread.
Q: How can I reduce the compiled size of my sketch?
A: A significant portion of the binary is Emscripten JS bundling overhead. The wasm_compiler_settings.py in the FastLED repo can tune this. Using --release produces a ~1/3 smaller binary than --quick.
Development
./install
./test
./lint
1 maintainer
Release files for fastled 2.0.21
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| fastled-2.0.21-py3-none-win_arm64.whl | Python 3 | none | Windows ARM64 | Details |
| fastled-2.0.21-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details |
| fastled-2.0.21-py3-none-manylinux_2_28_x86_64.whl | Python 3 | none | Linux glibc 2.28+ x86-64 | Details |
| fastled-2.0.21-py3-none-manylinux_2_28_aarch64.whl | Python 3 | none | Linux glibc 2.28+ ARM64 | Details |
| fastled-2.0.21-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details |
| fastled-2.0.21-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details |
Total release size: 83.2 MB
Release files / fastled-2.0.21-py3-none-win_arm64.whl
| Download URL | fastled-2.0.21-py3-none-win_arm64.whl |
|---|---|
| Size | 10.8 MB |
| Tags | Python 3 Windows ARM64 |
|
SHA-256 checksum How to use checksums |
025e9a757df1093186b5473d6255185155c56c022772fd5fe7a4311c24409499
|
|
BLAKE2b-256 checksum How to use checksums |
1409e5f805c2d3fb38fe74f860f4c7a125a9d18a5cc4cc384eccb822bffbaa82
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / fastled-2.0.21-py3-none-win_amd64.whl
| Download URL | fastled-2.0.21-py3-none-win_amd64.whl |
|---|---|
| Size | 10.8 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
4b71eed4a102b2a84617da691e1e9177101e931cd52fe22605ef508979faf4f9
|
|
BLAKE2b-256 checksum How to use checksums |
f6e0042e65a813cca3e8f583a136c4057c1ae05a7d0834ffa8f01ef5025e0b74
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / fastled-2.0.21-py3-none-manylinux_2_28_x86_64.whl
| Download URL | fastled-2.0.21-py3-none-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 19.4 MB |
| Tags | Linux glibc 2.28+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
2518f3a9fc0311d1776f97cc1f06d56856bab3a9b57d0ca9bac62520c21867b7
|
|
BLAKE2b-256 checksum How to use checksums |
0d2ff0e4ee6571ac90b4bc550d75ce616316406cb00e89dbe303f8e7f2b80ffe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / fastled-2.0.21-py3-none-manylinux_2_28_aarch64.whl
| Download URL | fastled-2.0.21-py3-none-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 19.7 MB |
| Tags | Linux glibc 2.28+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
d1fd81f26a6bad54e838d7fc49bb81abe5971bad73877f556fc34416caea82e9
|
|
BLAKE2b-256 checksum How to use checksums |
8a3d654ceae71202ac8f53e61b33526a85f26fcde702085e86ec3c07483a343c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / fastled-2.0.21-py3-none-macosx_11_0_arm64.whl
| Download URL | fastled-2.0.21-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 11.2 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b5a0ea8e78e316cb62c45f28432ff93b4d62d21503d1233107db412c8632d0f1
|
|
BLAKE2b-256 checksum How to use checksums |
9cee732ea1ee1d2bdc833211f5216affe12cfa3d3b4a0cb9eeb6585f66b1502c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / fastled-2.0.21-py3-none-macosx_10_12_x86_64.whl
| Download URL | fastled-2.0.21-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 11.2 MB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
99f6ebb82576c5468807959700bff33d00f54fd7303bbbd25409abc4f24037c3
|
|
BLAKE2b-256 checksum How to use checksums |
87aad32077e52e21360e32b5effc39807d24aa52ce265f9e8f0c8f96dd8e6b0a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency log
