rust-rodio-wsl2-audio

name	rust-rodio-wsl2-audio
description	Fix Rust audio compilation and runtime issues on WSL2 using rodio/cpal. Use when: (1) Build fails with "The system library 'alsa' required by crate 'alsa-sys' was not found", (2) Cannot install libasound2-dev without sudo access, (3) Runtime error "Unknown PCM default" or "cannot find card '0'" even after successful compilation. Covers compilation workaround using manual .deb extraction AND runtime fix using ALSA-to-PulseAudio routing.
author	Claude Code
version	2.0.0
date	"2026-01-23T00:00:00.000Z"

Rust Audio (rodio) on WSL2

Problem

Compiling and running Rust projects using rodio (or cpal) for audio on WSL2 fails at two stages:

1. Compile time: Missing ALSA development headers
2. Runtime: ALSA can't find audio devices because WSL2 uses PulseAudio via WSLg

Context / Trigger Conditions

Compilation Error

The system library `alsa` required by crate `alsa-sys` was not found.
The file `alsa.pc` needs to be installed and the PKG_CONFIG_PATH environment variable must contain its parent directory.

Runtime Error (after successful compilation)

ALSA lib confmisc.c:855:(parse_card) cannot find card '0'
ALSA lib pcm.c:2721:(snd_pcm_open_noupdate) Unknown PCM default
thread 'main' panicked at ... InitFailed

Solution

Part 1: Compilation Workaround (Without sudo)

If you can't install libasound2-dev via apt:

# 1. Download the dev package without installing
cd /tmp
apt-get download libasound2-dev

# 2. Extract the package
mkdir -p /tmp/alsa-dev
dpkg-deb -x libasound2-dev_*.deb /tmp/alsa-dev

# 3. Fix the pkg-config file to point to extracted location
cat > /tmp/alsa-dev/usr/lib/x86_64-linux-gnu/pkgconfig/alsa.pc << 'EOF'
prefix=/tmp/alsa-dev/usr
exec_prefix=/tmp/alsa-dev/usr
libdir=/usr/lib/x86_64-linux-gnu
includedir=${prefix}/include

Name: alsa
Description: Advanced Linux Sound Architecture (ALSA) - Library
Version: 1.2.11
Libs: -L${libdir} -lasound
Cflags: -I${includedir}
EOF

# 4. Create the development symlink (links to system runtime library)
mkdir -p /tmp/alsa-dev/usr/lib/x86_64-linux-gnu
ln -sf /usr/lib/x86_64-linux-gnu/libasound.so.2 \
       /tmp/alsa-dev/usr/lib/x86_64-linux-gnu/libasound.so

# 5. Build with environment variables set
PKG_CONFIG_PATH=/tmp/alsa-dev/usr/lib/x86_64-linux-gnu/pkgconfig \
LIBRARY_PATH=/tmp/alsa-dev/usr/lib/x86_64-linux-gnu:$LIBRARY_PATH \
cargo build

Part 2: Runtime Fix - ALSA to PulseAudio Routing

This is the key to making audio actually work on WSL2!

# 1. Download and extract the ALSA PulseAudio plugins
cd /tmp
apt-get download libasound2-plugins
mkdir -p /tmp/alsa-plugins
dpkg-deb -x libasound2-plugins*.deb /tmp/alsa-plugins

# 2. Create ~/.asoundrc to route ALSA through PulseAudio
cat > ~/.asoundrc << 'EOF'
# Route ALSA through PulseAudio for WSL2 compatibility
pcm.!default {
    type pulse
}

ctl.!default {
    type pulse
}
EOF

# 3. Run your application with ALSA_PLUGIN_DIR set
ALSA_PLUGIN_DIR=/tmp/alsa-plugins/usr/lib/x86_64-linux-gnu/alsa-lib \
./target/debug/your-app

Complete One-Liner Setup

# Run this once to set up everything
cd /tmp && \
apt-get download libasound2-dev libasound2-plugins && \
mkdir -p /tmp/alsa-dev /tmp/alsa-plugins && \
dpkg-deb -x libasound2-dev_*.deb /tmp/alsa-dev && \
dpkg-deb -x libasound2-plugins*.deb /tmp/alsa-plugins && \
mkdir -p /tmp/alsa-dev/usr/lib/x86_64-linux-gnu && \
ln -sf /usr/lib/x86_64-linux-gnu/libasound.so.2 /tmp/alsa-dev/usr/lib/x86_64-linux-gnu/libasound.so && \
cat > /tmp/alsa-dev/usr/lib/x86_64-linux-gnu/pkgconfig/alsa.pc << 'PCEOF'
prefix=/tmp/alsa-dev/usr
exec_prefix=/tmp/alsa-dev/usr
libdir=/usr/lib/x86_64-linux-gnu
includedir=${prefix}/include
Name: alsa
Description: ALSA
Version: 1.2.11
Libs: -L${libdir} -lasound
Cflags: -I${includedir}
PCEOF
cat > ~/.asoundrc << 'ASOUNDEOF'
pcm.!default { type pulse }
ctl.!default { type pulse }
ASOUNDEOF
echo "Setup complete!"

Build and Run Commands

# Build
PKG_CONFIG_PATH=/tmp/alsa-dev/usr/lib/x86_64-linux-gnu/pkgconfig \
LIBRARY_PATH=/tmp/alsa-dev/usr/lib/x86_64-linux-gnu \
cargo build

# Run with audio
ALSA_PLUGIN_DIR=/tmp/alsa-plugins/usr/lib/x86_64-linux-gnu/alsa-lib \
./target/debug/your-app

Verification

Compilation success:

PKG_CONFIG_PATH=/tmp/alsa-dev/usr/lib/x86_64-linux-gnu/pkgconfig \
LIBRARY_PATH=/tmp/alsa-dev/usr/lib/x86_64-linux-gnu \
cargo build 2>&1 | grep -E "(Compiling|Finished)"

Runtime success (no ALSA errors):

ALSA_PLUGIN_DIR=/tmp/alsa-plugins/usr/lib/x86_64-linux-gnu/alsa-lib \
./target/debug/your-app 2>&1 | grep -i alsa
# Should show NO output (no errors)

Audio test:

• You should hear audio through your Windows speakers/headphones
• WSLg routes the audio: App → ALSA → PulseAudio plugin → WSLg → Windows

Notes

• The runtime ALSA library (libasound.so.2) IS installed on most WSL2 distros
• Only the dev headers/symlink and plugins are missing
• PulseAudio socket exists at /mnt/wslg/runtime-dir/pulse/native
• The ~/.asoundrc file persists across sessions
• ALSA_PLUGIN_DIR must be set each time you run the app (or add to shell profile)
• Consider adding to ~/.bashrc: export ALSA_PLUGIN_DIR=/tmp/alsa-plugins/usr/lib/x86_64-linux-gnu/alsa-lib

Troubleshooting

Still getting ALSA errors?

1. Verify PulseAudio is running: ls /mnt/wslg/runtime-dir/pulse/
2. Check plugin exists: ls $ALSA_PLUGIN_DIR/libasound_module_pcm_pulse.so
3. Verify .asoundrc: cat ~/.asoundrc

No sound but no errors?

1. Check Windows volume mixer
2. Verify WSLg audio: paplay /usr/share/sounds/alsa/Front_Center.wav (if installed)

References

• WSLg Audio Architecture: https://github.com/microsoft/wslg
• ALSA PulseAudio Plugin: https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/PerfectSetup/
• rodio crate: https://docs.rs/rodio
• cpal ALSA backend: https://docs.rs/cpal