Deploy MusicGen v1.3.0: The Install Path Most Guides Skip

Most MusicGen install failures aren’t MusicGen’s fault. They’re a two-year-old PyTorch version pin colliding with whatever CUDA setup is already on your machine – and the fix isn’t a longer requirements.txt. It’s picking the right install path before you touch pip.

There are two ways to run MusicGen locally, and 90% of tutorials only show the harder one. This guide covers both, tells you which fits your use case, and walks through the exact commands for audiocraft 1.3.0 (the current PyPI release as of mid-2024) and the Hugging Face Transformers route that sidesteps the dependency mess entirely.

Which install path do you actually need?

Before anything else, decide what you’re building. MusicGen ships in two flavors:

• The audiocraft library (Meta’s original) – required for AudioGen, EnCodec, fine-tuning, or the Gradio demo. Official repo.
• Hugging Face Transformers integration – available from v4.31.0 onwards (per HF docs). No xformers. No PyTorch 2.1.0 pin.

Text-to-music inference only? Use Transformers – saves the dependency archaeology. Melody conditioning with chromagrams, training code, or AudioGen/EnCodec access? Use the audiocraft library. Most guides skip this fork in the road entirely, which is why issue trackers fill up with xformers CUDA mismatches from people who didn’t need xformers in the first place.

System requirements

The main audiocraft README says you “need a GPU” and stops there. The actual numbers live in the MusicGen doc.

Per the MusicGen doc: 16 GB VRAM minimum for the medium model (~1.5B parameters). The small model (300M) fits in 8 GB. Large (3.3B) wants 24 GB – community reports on GitHub confirm OOM even on an RTX 3090 if you don’t flush the cache between runs. CPU-only is technically possible but expect several minutes per 8-second clip on modern hardware, not seconds.

Install audiocraft 1.3.0

Order matters more than the commands. Install these in sequence, inside a fresh environment – the xformers CUDA mismatch that fills GitHub issues almost always traces back to torch being installed after audiocraft, not before.

# 1. Isolated environment
conda create -n audiocraft python=3.9
conda activate audiocraft

# 2. PyTorch FIRST
python -m pip install 'torch==2.1.0'

# 3. Build prerequisites
python -m pip install setuptools wheel

# 4. audiocraft
python -m pip install -U audiocraft

# 5. ffmpeg
conda install "ffmpeg<5" -c conda-forge

The reason ordering matters: xformers builds from source on some platforms. If pip’s isolated build environment can’t find torch at that moment, you get “No module named torch” even though torch is sitting in your env. Installing torch first closes that gap. (GitHub issues #248 and #230 both trace back to this exact sequence problem.)

Want the latest commits rather than the PyPI release? Swap step 4: python -m pip install -U git+https://[email protected]/facebookresearch/audiocraft#egg=audiocraft.

The lighter path: Transformers only

pip install --upgrade transformers scipy torch

from transformers import AutoProcessor, MusicgenForConditionalGeneration
processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")
inputs = processor(text=["lo-fi hip hop with vinyl crackle"], padding=True, return_tensors="pt")
audio_values = model.generate(**inputs, max_new_tokens=256)

No xformers. No version pin. No conda dance. The tradeoff is real, though: chromagram melody conditioning as a one-liner is gone, the Gradio demo is gone, and so are the training utilities. For pure inference it’s hard to argue against this path.

Which raises an interesting question: if the Transformers integration has been available since v4.31.0 and removes this much friction, why do so many tutorials still default to the full audiocraft install? Probably because most were written when the Transformers route didn’t exist – and nobody updated them.

First-time configuration

Model weights download on first use. The small model alone lands somewhere around 1-2 GB; all three together can hit 30+ GB. Set a cache directory before the first import – not after, or you’ll end up with two copies of the weights in two locations and a disk space puzzle:

export AUDIOCRAFT_CACHE_DIR=/path/to/big/disk/audiocraft_cache

Per the audiocraft README: this variable overrides the default Hugging Face model cache location for audiocraft models. For the Transformers-side cache, check the HF Transformers cache docs – it’s a separate setting.

Verify the install

Smoke test first:

python -c "import audiocraft; print(audiocraft.__version__)"
# should print 1.3.0

Then a short generation to confirm GPU access:

import torchaudio
from audiocraft.models import MusicGen
from audiocraft.data.audio import audio_write

model = MusicGen.get_pretrained('small')
model.set_generation_params(duration=8)
wav = model.generate(['ambient piano with soft rain'])
audio_write('test', wav[0].cpu(), model.sample_rate, strategy="loudness")

If test.wav appears and plays, you’re done. Gradio UI available too – python -m demos.musicgen_app --share – but only if you cloned the repo. The pip install does not include the demos folder.

Common errors

Three failures account for most of the noise in the issue tracker.

1. “xFormers can’t load C++/CUDA extensions” – the most reported one. The warning text is usually: xFormers was built for PyTorch 2.0.1+cu118 with CUDA 1108 (you have 2.0.1+cpu). Translation: pip grabbed the CPU wheel of torch. Fix: uninstall torch and reinstall with the CUDA index URL matching your driver version: pip install torch==2.1.0 --index-url https://download.pytorch.org/whl/cu118. (See issue #248.)

2. CUDA out of memory on a 24 GB card. Community issue #296 documents OOM on an RTX 3090 running AudioGen without cache cleanup between runs. Call torch.cuda.empty_cache() between generations, keep duration at 15 seconds max on the large model, and set PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128 before Python starts.

3. “No module named triton” – harmless on non-NVIDIA setups. It’s a warning. Ignore it unless you’re on Linux with an NVIDIA card, in which case pip install triton unlocks some xformers optimizations.

Upgrade and uninstall

Coming from 1.1.0 or 1.2.0? pip install -U audiocraft handles it. The MusicGen public API has been stable across recent releases – but if you have custom checkpoints from before 1.1.0, check the changelog before upgrading; the tokenizer and interleaving pattern reportedly changed in that release.

Clean uninstall:

pip uninstall audiocraft xformers

# Weights can run 30+ GB
rm -rf ~/.cache/huggingface/hub/models--facebook--musicgen-*
rm -rf ~/.cache/torch/hub/checkpoints/ # if you used melody/Demucs

The license split most people miss

Code is MIT. Model weights are CC-BY-NC 4.0 – as stated in the LICENSE_weights file on the audiocraft repo. Your generated audio inherits the weights’ license. Non-commercial only. The code/weights split is easy to miss because tutorial comment sections are full of people assuming MIT covers everything. It doesn’t.

Curious about why MusicGen generates coherent audio from a text prompt at all? The architecture uses a 32kHz EnCodec tokenizer with 4 codebooks sampled at 50 Hz, feeding a single-stage autoregressive Transformer. The token interleaving pattern is the trick that makes it work without a cascade of models. Full details in the Simple and Controllable Music Generation paper (arXiv:2306.05284).

FAQ

Can I run MusicGen on Python 3.10 or 3.11?

3.10 works for most people. 3.11 is where things get brittle – transitive dependencies like spacy and xformers wheels can misbehave. Hit a compile error you can’t decode on 3.11? Go back to 3.9. Python 3.12 is not currently supported; Issue #476 tracks the spacy build failure blocking it.

Do I need a GPU?

No – but you’ll want one. CPU inference doesn’t error out, it just takes long enough to be useless for iteration. Use the Hugging Face Spaces hosted demo for quick experiments.

Which model should I start with?

Start with small (300M). It fits in 8 GB VRAM and downloads fast enough that you’ll know within 10 minutes whether MusicGen suits your project. Medium (1.5B) is where fidelity noticeably improves – that jump is worth it. Large (3.3B) is a different calculation: generation time roughly doubles from medium to large, and many users report the quality gain is smaller than the VRAM cost implies. Run the verification snippet above with small first and time your first generation. That single number will tell you more than any benchmark.