YuE2-3B on RTX 5090: the 32GB card the library caps at 22 GiB

What You'll Build

A whole song — vocals and accompaniment, 48 kHz stereo — written on one RTX 5090 from a style prompt and lyrics, delivered together with the editable ABC score the model planned it from, so a changed melody or harmony can be re-rendered as the same piece.

Hardware data: RTX 5090 (32GB VRAM) · unmeasured on this card by anyone · default settings use 22 GiB of it at most · See benchmark data

⚠️ The weights are non-commercial. YuE2's code is Apache 2.0, but the checkpoints this recipe downloads are CC BY-NC 4.0. The repository's LICENSE says the weights are "licensed under Creative Commons Attribution-NonCommercial 4.0 International" and scopes that to "the YuE2 checkpoint weights in model.safetensors, or the corresponding" model files. On GitHub the vendor splits the two explicitly: "YuE2's first-party code, agent skill, and documentation are licensed under" Apache 2.0, while "Model weights are separately licensed under" CC BY-NC 4.0. The licence text names the weights and does not address the audio you generate with them — if you intend to release or monetise output, read the full licence rather than this paragraph.

ℹ️ One runtime, and it is a Python wheel. YuE2-3B runs through the vendor's own yue2 package on Linux with CUDA. There is no llama.cpp, Ollama, LM Studio or ComfyUI path — see Troubleshooting for what the GGUF files on the Hub are and are not.

⚠️ No speed figure on this page is this card's. The vendor published measurements for two GPUs, neither of them this one. A third party has since posted figures for this card — the author of the audio.cpp port, for his own C++ engine on a Q8 quantisation, not for the vendor's Python runtime documented here; the Troubleshooting section below sets out why none of it transfers. The fit below comes from the shipped source; a borrowed number always says whose card it came from.

Requirements

The vendor's two requirement lines are "Linux · Python 3.10+ · 24GB NVIDIA GPU with BF16 support." on the model card and "Linux · Python 3.12 · NVIDIA GPU with BF16 support and 24 GB VRAM." in the GitHub repository. Both are written for a 24GB board and neither says what to do with more; the answer, worked out in Troubleshooting, is that you have to ask for it.

Installation

1. Install the inference package into a dedicated virtual environment

These three lines are the model card's quick start, unchanged:

python3 -m venv .yue2 && source .yue2/bin/activate
python -m pip install huggingface-hub==0.36.2
hf download m-a-p/YuE2-3B yue2_infer-0.1.5-py3-none-any.whl --local-dir .
python -m pip install ./yue2_infer-0.1.5-py3-none-any.whl

Run them inside a virtual environment created for this and nothing else. The wheel pins all eight of its runtime dependencies exactly rather than as minimums — torch==2.10.0, transformers==4.57.6, huggingface-hub==0.36.2, safetensors==0.7.0, tiktoken==0.12.0, numpy==2.2.6, soundfile==0.13.1, accelerate==1.13.0, read from its METADATA and matching the repository's pyproject.toml — and an == pin downgrades whatever it finds instead of accepting it. Someone has already paid for that: a ComfyUI user reported on 2026-09-10 that installing this wheel over a working install pulled PyTorch back from 2.11 to 2.10 and broke their launcher.

The wheel this recipe installs is 0.1.5, the version the model card's quick start names; the repository tree is 0.1.6, and the source files this recipe cites are byte-identical between the two, so everything below holds for either install path. The pins also match the versions the vendor used for the numbers in Results.

Install PyTorch's CUDA build first if your environment would otherwise resolve a CPU-only wheel.

2. Confirm the card and the dependencies

The package ships a yue2 command whose doctor subcommand prints your card's name, its memory in GiB and its compute capability, alongside the resolved version of every pinned dependency:

yue2 doctor

Read dependencies_ready and the cuda array in the JSON it prints. The memory figure it reports is the one the budget clamp below divides into, and it is the driver's number rather than the number on the box. doctor reports environment readiness only — the vendor's own note in that output is explicit that it is not an acceptance test.

3. Let the loader fetch the weights

The first pipeline call downloads what it needs from m-a-p/YuE2-3B and m-a-p/YuE2-Vae. The loader uses an explicit allow-list (src/yue2/storage.py L33-39) rather than a full clone, so the demo audio and images in those repositories are not downloaded — that is why the Storage row above is 7.79 GB and not the 7.83 GB the two repositories hold in total.

Running

Load the pipeline once, then generate:

from pathlib import Path
from yue2 import YuE2Pipeline

pipe = YuE2Pipeline.from_pretrained("m-a-p/YuE2-3B", device="cuda")

Then run the vendor's own example prompt, which is shipped inside the model repository:

import json
from huggingface_hub import hf_hub_download

repo = "m-a-p/YuE2-3B"
prompt_path = hf_hub_download(repo, "examples/tonight-awake.json")
demo = json.loads(Path(prompt_path).read_text(encoding="utf-8"))
style, lyrics = demo["style"], demo["lyrics"]

song = pipe(style=style, lyrics=lyrics, cot="full", seed=demo["seed"])
song.save("song.flac")
song.save_artifacts("outputs/song")  # ABC, tokens, latents, audio and settings

song.flac is the finished stereo song. outputs/song holds the ABC score, the semantic tokens, the acoustic latents and the exact settings used — edit score.abc and pass it back as abc= to re-render the same song with a revised melody or harmony.

If you want the pipeline to be allowed to use more than 22 GiB of the card, pass the budget on the same call — the next section explains why the default will not:

pipe = YuE2Pipeline.from_pretrained("m-a-p/YuE2-3B", device="cuda", memory_budget_gib=32)

The same three modes are available from the shell, which is the easier path when you want to queue several songs:

yue2 generate --cot full --style "Mandarin funk, nu-disco" --lyrics-file lyrics.txt --output outputs/song

--budget 32 is the shell equivalent of the memory_budget_gib=32 above, and it carries the same condition: add it only if you want the ceiling raised. Left off, the run stays under the 22 GiB default — the same ceiling the vendor's published figures were taken under.

cot="full" plans melody and chords and is the default; cot="melody" plans melody only and is what the vendor recommends for covers; cot="off" generates with no symbolic plan. The default decoder is m-a-p/YuE2-Vae; pass vae="m-a-p/YuE2-Vae-legacy" to from_pretrained to reproduce the published benchmark protocol instead.

Results

Nothing in this section was measured on this card. Two of the three quantities below are properties of the checkpoint and hold anywhere; the rest belongs to the vendor's own GPU and is labelled as such.

• Speed — no figure for this card, and the missing one may be higher or lower. The vendor's consumer measurement is 139.48 LM tokens/s in cot="full", producing 214.85 s of audio in 71.04 s of wall clock, headlined on the card as "A 3.6-minute song in 71 seconds on an RTX 4090." (model card). The uncertainty here runs the opposite way to the usual case, because the card the vendor measured is the older of the two — but a direction is not a prediction, and while YuE2-3B has since been run on Blackwell — by us on an RTX 5060 Ti 16GB, and by the audio.cpp port author on this very card through a different engine — neither is a measurement of the vendor's Python runtime on an RTX 5090, so do not read that row as a floor this card is guaranteed to clear. Method, verbatim: "HF: PyTorch 2.10, Transformers 4.57.6, no quantization, default YuE2-Vae." and "4090 values average 32 warm requests per mode". The runtime is described as "The HF package uses PyTorch, CUDA graphs, and FlashAttention, with BF16 AR/NAR and FP32 VAE."
• VRAM usage — the vendor's readings on the vendor's board: 11.18 GiB peak in full mode, 11.02 GiB in melody, 11.09 GiB in off, with maximum-context testing separately reported at 14.08 GiB. All are NVML readings — "NVML records the full-run GPU peak." — so they count the CUDA context and not only the allocator.
• How much of that peak is portable, and where the accounting stops: two figures inside it are exact byte counts and identical on any card that loads this checkpoint — the AR/NAR weights at 6.763 GiB in BF16 and the VAE decoder at 0.494 GiB, read from the Hugging Face tree API on 2026-09-10 (YuE2-3B, YuE2-Vae). Adding them to each other describes no instant in the run. The pipeline evicts the language model to host RAM before the decoder reaches the card: decode() moves the AR/NAR model to the host (src/yue2/pipeline.py L323-324) and empties the CUDA cache (L326) before the VAE is loaded on the CPU and moved onto the device (L331-333), and returns it to the host in the finally (L354); L222 is the only line in the module that ever puts the AR/NAR model on the device. Everything else in that peak — KV cache, activations, CUDA-graph pools, CUDA context — the vendor reports only as part of the total, and the card does not say which stage the NVML reading came from, so no split is offered here.
• The 32GB is not the operative number. Subtracting an 11.18 GiB peak from the card leaves 20.82 GiB of raw capacity, but the pipeline never gets to use most of it: at defaults it caps itself at 22 GiB regardless of how large the card is. The next section shows the arithmetic and the one argument that changes it.
• Throughput: "One song at a time." The pipeline is not a batching server; the batch subcommand queues requests, it does not run them concurrently on this path.
• Quality notes: the vendor reports a 6.7316 SongBench average for YuE2 and 6.9632 for its best-of-8 setting across 192 WildSongBench prompts, using the legacy decoder. Those are the vendor's own automatic metrics under its own candidate-selection protocol, not an independent evaluation, and they say nothing about which GPU produced them.

No benchmark exists for this pair. If you run it, please send us the numbers — a measured figure replaces the vendor's on /check/yue2-3b/rtx-5090, which is where the live data for this pair lands.

Troubleshooting

The default budget ignores your last 8GB, and that is deliberate

YuE2Pipeline.__init__ accepts a memory_budget_gib argument that defaults to 24 — a constant, not a reading of your hardware — and then clamps it against the device: it takes the smaller of memory_budget_gib − 2 and total_memory − 2 GiB and applies it with set_per_process_memory_fraction (src/yue2/pipeline.py L161-165). On a 24GB board the two terms are effectively the same and the card is what binds. On this card they are not close:

So the term that binds on a 32GB board is the library's own default, not the hardware. The card's extra capacity buys exactly nothing until you say otherwise, and the fix is one argument: memory_budget_gib=32 (or --budget 32) moves the ceiling onto the total_memory − 2 GiB term, roughly 30 GiB. Use the figure yue2 doctor reports rather than the number on the box — the driver's total is a little under the nameplate capacity, so the resulting ceiling is a little under 30 GiB.

Two caveats before you reach for it. Nothing published needs more than 22 GiB: the vendor's ordinary peak is 11.18 GiB and its maximum-context peak is 14.08 GiB, both comfortably inside the default, so raising the budget is headroom for future settings rather than a fix for anything documented. And the budget is a ceiling, not a reservation — raising it does not make the pipeline allocate more, it only stops the allocator refusing.

Memory budget must leave room for a 2GiB reserve — and where the 16GB floor comes from

The same clamp raises this error when the budget it computes is not positive, and it is also what decides the smallest card this install runs on. Because only capacity enters the expression, the floor is derivable without measuring anything:

• 32GB: capped at 22 GiB by the default, or about 30 GiB when the budget is raised. Neither figure is a constraint on any published workload.
• 16GB: about 14 GiB, and the whole range fits. Measured here on an RTX 5060 Ti 16GB (2026-09-10, WSL2, driver 591.86): an ordinary song peaked at 10.05 GiB — below the vendor's own 4090 figure — and a deliberately full-context song run with the second CFG branch, the worst case the library can be put in, peaked at 13.48 GiB on the device and 12.64 GiB in-process, leaving 1.29 GiB under the clamp. No OOM in any run. An earlier version of this page said a maximum-context song would not fit 16GB; that was wrong, and wrong in an instructive way — it compared the vendor's 14.08 GiB, which is a device peak, against a ceiling set_per_process_memory_fraction imposes on the process. A device peak includes whatever a monitor is holding; the clamp never sees it.
• 12GB: about 10 GiB, below the 11.18 GiB the vendor measured for the ordinary case. The documented install does not fit, and the failure surfaces as an allocator error rather than as this message.

Shrinking the context is not a way out of the 12GB case or any other: the generation config refuses any value but 24576 (src/yue2/protocol.py L54-55). Note also that a budget of 12 or lower halves the VAE core frame count, which alters the decode path rather than only the memory cap — another reason not to treat this argument as a pure dial.

One setting moves memory the other way, and the model card recommends trying it. Its tuning table offers cfg_scale=1.2 to "Experiment with stronger text guidance", and any guidance other than 1 makes the sampler build a second, unconditional branch (src/yue2/sampling.py L92) whose KV cache is allocated with the branch count as its leading dimension (src/yue2/cuda_graph.py L90). So raising it costs additional memory. How much is not published, and it cannot be recovered from the vendor's three-mode table: cot="off" already runs two branches — its default guidance is 1.01 (protocol.py L106) and the branch test is cfg_scale == 1 — yet it is measured at 11.09 GiB, below the 11.18 GiB of cot="full" on one branch. The three modes differ in more than their branch count, so the gaps between them cannot be used to price the second branch. This is the one place where the budget argument above is worth reaching for, since the extra branch is exactly the kind of unmeasured demand the default 22 GiB ceiling would meet first.

Does the pinned torch==2.10.0 have kernels for a Blackwell card?

This is the failure a new-architecture owner reasonably worries about, and the pin makes it checkable rather than a matter of hope. The PyPI release metadata for torch 2.10.0 pins nvidia-cuda-runtime-cu12==12.8.90 and its siblings on Linux x86_64, so the wheel pip resolves is the CUDA 12.8 build. In PyTorch's own release script the 12.8 case extends the base architecture list 7.0;7.5;8.0;8.6;9.0 with 10.0;12.0, under a comment reading "+Hopper/Blackwell support" (.ci/manywheel/build_cuda.sh). The Blackwell targets are compiled in.

Nothing in the YuE2 package narrows that further. Its only hard hardware test is torch.cuda.is_bf16_supported(), which raises The unquantized preset requires CUDA BF16 support when it fails (src/yue2/pipeline.py L159-160); the attention backend is picked from the dtype and a head dimension of 128 and falls back from PyTorch's fused FlashAttention to cuDNN to plain SDPA rather than erroring; and there is no flash-attn package in the dependency list at all, which is what the runtime's own comment says: "CUDA normally uses PyTorch's fused SDPA without an external flash package." The one place compute capability is read is the opt-in quantization="fp8" path (src/yue2/quantization.py L71-72), and its own docstring warns that "No quantized quality or speed claim is implied by enabling this module." — every published number was taken at the default quantization="none", so leave it there.

The GGUF files on the Hub are not a runtime path

A GGUF conversion of this model exists at audio-cpp/Yue2-3B-GGUF, converted from the same upstream revision this recipe pins. It is not a llama.cpp or Ollama artifact — it targets a separate C++ engine, 0xShug0/audio.cpp, and the GGUF repository's own card says that engine's support for this model is still in development and due to land on the engine's dev branch. That changed hours after this page was first published. The port landed on the engine's dev branch on 2026-09-10 at 17:09 UTC — head 3caeba87, 29 paths including src/models/yue2/, include/engine/models/yue2/ and docs/models/yue2.md — and its author reports a peak below 9 GB and a real-time factor of 0.23 to 0.28 through that engine's UI on an RTX 5090 (vendor issue #163). Treat none of it as transferable here: a different engine running a Q8 quantisation, self-reported by the person who wrote the port, and by his own announcement the model sits in a branch for community testing that “won’t be included in the prebuilt binaries before merging” (discussion 3). If you want it, build the dev branch and expect to be an early tester. This page documents the vendor's Python runtime, which is what every number above was measured on.

No community reports yet

YuE2-3B was published on 2026-09-09. Re-checked on 2026-09-10: m-a-p/YuE2-Vae still has an empty discussions tab and m-a-p/YuE2-3B has a single thread, opened that day — a usage question about getting reliably instrumental output, tried in the hosted Space and naming no GPU. The identical endpoint against the organisation's YuE v1 model returns ten threads, so the near-silence is the release's age, not a failed query. The only thread that reports a run is the port author's, and it is through his own C++ engine on a Q8 quantisation rather than the vendor's Python runtime this page documents — a thread count decays by the hour, that predicate does not. A full enumeration of every GitHub issue mentioning YuE2 on 2026-09-10 turns up only items from the launch, all of them either vendor pull requests, requests to port the model to a third-party engine, or bugs in a community ComfyUI wrapper; none is a report from anyone running a Blackwell card. The hardware threads sitting in the vendor's own tracker — AMD, macOS and GGUF alike — all predate YuE2 and were filed against YuE v1, a different model with a different runtime, so nothing in them transfers. The package carries no ROCm, HIP or Metal code path, and the vendor documents no AMD or Apple install route.

If you hit something, please report it via the submission form.