From 16a6a2ae13d2ba8062bbccb7df56b911ddd5f097 Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Sun, 26 Apr 2026 15:54:22 +0000
Subject: [PATCH] feat(backend): add global libc preference

---
 crates/vfox/src/config.rs      |   2 +-
 crates/vfox/src/plugin.rs      |   8 +-
 crates/vfox/src/runtime.rs     |   7 +-
 crates/vfox/src/vfox.rs        |  20 ++-
 docs/lang/node.md              |   3 +
 docs/mise-cookbook/docker.md   |  14 +-
 schema/mise.json               |   5 +
 settings.toml                  |  14 ++
 src/backend/aqua.rs            | 283 +++++++++++++++++++++++++++++----
 src/backend/asset_matcher.rs   |  19 ++-
 src/backend/platform_target.rs |  13 ++
 src/cache.rs                   |   7 +-
 src/config/settings.rs         |   8 +
 src/platform.rs                |  38 +++--
 src/plugins/core/bun.rs        |  10 +-
 src/plugins/core/node.rs       |  31 +++-
 src/plugins/core/python.rs     |  25 ++-
 src/plugins/vfox_plugin.rs     |   7 +
 18 files changed, 439 insertions(+), 75 deletions(-)

diff --git a/crates/vfox/src/config.rs b/crates/vfox/src/config.rs
index ba6839f21d..4eecc71aba 100644
--- a/crates/vfox/src/config.rs
+++ b/crates/vfox/src/config.rs
@@ -55,7 +55,7 @@ pub(crate) fn env_type() -> Option<String> {
         if let Ok(val) = std::env::var("MISE_LIBC") {
             match val.to_lowercase().as_str() {
                 "musl" => return Some("musl".to_string()),
-                "gnu" => return Some("gnu".to_string()),
+                "glibc" | "gnu" => return Some("gnu".to_string()),
                 _ => {} // invalid value ignored, fall through to runtime detection
             }
         }
diff --git a/crates/vfox/src/plugin.rs b/crates/vfox/src/plugin.rs
index b49b440c99..79f3cd6218 100644
--- a/crates/vfox/src/plugin.rs
+++ b/crates/vfox/src/plugin.rs
@@ -24,6 +24,7 @@ pub enum PluginSource {
 pub struct Plugin {
     pub name: String,
     pub dir: PathBuf,
+    pub runtime_env_type: Option<String>,
     source: PluginSource,
     lua: Lua,
     metadata: OnceCell<Metadata>,
@@ -41,6 +42,7 @@ impl Plugin {
         Ok(Self {
             name,
             dir: dir.to_path_buf(),
+            runtime_env_type: None,
             source: PluginSource::Filesystem(dir.to_path_buf()),
             lua,
             metadata: OnceCell::new(),
@@ -57,6 +59,7 @@ impl Plugin {
         Ok(Self {
             name: name.to_string(),
             dir: dummy_dir,
+            runtime_env_type: None,
             source: PluginSource::Embedded(embedded),
             lua,
             metadata: OnceCell::new(),
@@ -209,7 +212,10 @@ impl Plugin {
 
             let metadata = self.load_metadata()?;
             self.set_global("PLUGIN", metadata.clone())?;
-            self.set_global("RUNTIME", Runtime::get(self.dir.clone()))?;
+            self.set_global(
+                "RUNTIME",
+                Runtime::get(self.dir.clone(), self.runtime_env_type.as_deref()),
+            )?;
             self.set_global("OS_TYPE", config::os())?;
             self.set_global("ARCH_TYPE", config::arch())?;
 
diff --git a/crates/vfox/src/runtime.rs b/crates/vfox/src/runtime.rs
index a65fb07fdb..7dc7a79d5b 100644
--- a/crates/vfox/src/runtime.rs
+++ b/crates/vfox/src/runtime.rs
@@ -24,14 +24,17 @@ static RUNTIME: Lazy<Mutex<Runtime>> = Lazy::new(|| {
 });
 
 impl Runtime {
-    pub(crate) fn get(plugin_dir_path: PathBuf) -> Runtime {
+    pub(crate) fn get(plugin_dir_path: PathBuf, env_type_override: Option<&str>) -> Runtime {
         let mut runtime = RUNTIME.lock().unwrap().clone();
         runtime.plugin_dir_path = plugin_dir_path;
+        if let Some(env_type) = env_type_override {
+            runtime.env_type = Some(env_type.to_string());
+        }
         runtime
     }
 
     pub(crate) fn with_platform(plugin_dir_path: PathBuf, os: &str, arch: &str) -> Runtime {
-        let mut runtime = Self::get(plugin_dir_path);
+        let mut runtime = Self::get(plugin_dir_path, None);
         runtime.os = os.to_string();
         runtime.arch = arch.to_string();
         runtime.env_type = None; // target libc is unknown in cross-platform context
diff --git a/crates/vfox/src/vfox.rs b/crates/vfox/src/vfox.rs
index 4dfd1fda3c..e0316a34ae 100644
--- a/crates/vfox/src/vfox.rs
+++ b/crates/vfox/src/vfox.rs
@@ -55,6 +55,8 @@ pub struct Vfox {
     pub cmd_env: Option<IndexMap<String, String>>,
     /// Optional GitHub token for Lua http requests to GitHub API endpoints.
     pub github_token: Option<String>,
+    /// Optional runtime env type (`gnu` or `musl`) exposed to plugin hooks.
+    pub runtime_env_type: Option<String>,
     log_tx: Option<mpsc::Sender<String>>,
 }
 
@@ -123,7 +125,9 @@ impl Vfox {
     }
 
     pub fn get_sdk(&self, name: &str) -> Result<Plugin> {
-        Plugin::from_name_or_dir(name, &self.plugin_dir.join(name))
+        let mut plugin = Plugin::from_name_or_dir(name, &self.plugin_dir.join(name))?;
+        plugin.runtime_env_type = self.runtime_env_type.clone();
+        Ok(plugin)
     }
 
     fn get_sdk_with_env(&self, name: &str) -> Result<Plugin> {
@@ -146,12 +150,16 @@ impl Vfox {
         // Check filesystem first - allows user to override embedded plugins
         let plugin_dir = self.plugin_dir.join(sdk);
         if plugin_dir.exists() {
-            return Plugin::from_dir(&plugin_dir);
+            let mut plugin = Plugin::from_dir(&plugin_dir)?;
+            plugin.runtime_env_type = self.runtime_env_type.clone();
+            return Ok(plugin);
         }
 
         // Fall back to embedded plugin if available
         if let Some(embedded) = crate::embedded_plugins::get_embedded_plugin(sdk) {
-            return Plugin::from_embedded(sdk, embedded);
+            let mut plugin = Plugin::from_embedded(sdk, embedded)?;
+            plugin.runtime_env_type = self.runtime_env_type.clone();
+            return Ok(plugin);
         }
 
         // Otherwise install from registry
@@ -175,7 +183,9 @@ impl Vfox {
             debug!("Installing plugin {sdk}");
             xx::git::clone(url.as_ref(), &plugin_dir, &Default::default())?;
         }
-        Plugin::from_dir(&plugin_dir)
+        let mut plugin = Plugin::from_dir(&plugin_dir)?;
+        plugin.runtime_env_type = self.runtime_env_type.clone();
+        Ok(plugin)
     }
 
     pub fn uninstall_plugin(&self, sdk: &str) -> Result<()> {
@@ -588,6 +598,7 @@ impl Default for Vfox {
             skip_verification: false,
             cmd_env: None,
             github_token: None,
+            runtime_env_type: None,
             log_tx: None,
         }
     }
@@ -615,6 +626,7 @@ mod tests {
                 skip_verification: false,
                 cmd_env: None,
                 github_token: None,
+                runtime_env_type: None,
                 log_tx: None,
             }
         }
diff --git a/docs/lang/node.md b/docs/lang/node.md
index e4ae9ca10b..11621f4e79 100644
--- a/docs/lang/node.md
+++ b/docs/lang/node.md
@@ -108,6 +108,9 @@ mise settings node.flavor=musl
 mise settings node.flavor=glibc-217
 ```
 
+For the common musl case, `mise settings libc=musl` also selects Node's `musl`
+flavor when `node.flavor` is unset.
+
 ## Settings
 
 <script setup>
diff --git a/docs/mise-cookbook/docker.md b/docs/mise-cookbook/docker.md
index f549524ebb..73fcb6e58c 100644
--- a/docs/mise-cookbook/docker.md
+++ b/docs/mise-cookbook/docker.md
@@ -90,21 +90,21 @@ When the container starts with `~` mounted, users still see the system tools aut
 Any tools they install normally go to `~/.local/share/mise/installs` (on the mount) and
 take priority over system versions.
 
-## Overriding libc detection with MISE_LIBC
+## Overriding libc detection
 
 In minimal Docker images (scratch, busybox, distroless) where no dynamic linker
-files exist, mise may not detect whether the system uses musl or glibc. Set `MISE_LIBC`
-to force the detection:
+files exist, mise may not detect whether the system uses musl or glibc. Set `libc`
+or `MISE_LIBC` to force the detection:
 
 ```Dockerfile
 ENV MISE_LIBC=musl
 RUN mise install
 ```
 
-Valid values are `musl` and `gnu` (case-insensitive). Invalid values are silently
-ignored and mise falls back to runtime detection. When the mise binary is compiled
-for musl (the default for Linux releases), it will also fall back to musl
-automatically when no linker is detected.
+Valid values are `musl`, `glibc`, and `gnu` (case-insensitive, with `gnu` treated
+as glibc). Invalid values are silently ignored and mise falls back to runtime
+detection. When the mise binary is compiled for musl (the default for Linux
+releases), it will also fall back to musl automatically when no linker is detected.
 
 ## Task to run mise in a Docker container
 
diff --git a/schema/mise.json b/schema/mise.json
index 65609ae2d4..59cac0ad7c 100644
--- a/schema/mise.json
+++ b/schema/mise.json
@@ -1046,6 +1046,11 @@
             "type": "string"
           }
         },
+        "libc": {
+          "description": "Libc implementation to use for precompiled Linux binaries.",
+          "type": "string",
+          "enum": ["glibc", "gnu", "musl"]
+        },
         "libgit2": {
           "default": true,
           "description": "Use libgit2 for git operations, set to false to shell out to git.",
diff --git a/settings.toml b/settings.toml
index b855861564..f73a7fc43e 100644
--- a/settings.toml
+++ b/settings.toml
@@ -1065,6 +1065,20 @@ parse_env = "set_by_comma"
 rust_type = "BTreeSet<String>"
 type = "SetString"
 
+[libc]
+default_docs = '"glibc" | "musl"'
+description = "Libc implementation to use for precompiled Linux binaries."
+docs = """
+Libc implementation to use for precompiled Linux binaries. This is used by backends that publish
+separate glibc and musl builds. If unset, mise will detect the current system's libc.
+
+`gnu` is accepted as an alias for `glibc`.
+"""
+enum = ["glibc", "gnu", "musl"]
+env = "MISE_LIBC"
+optional = true
+type = "String"
+
 [libgit2]
 default = true
 description = "Use libgit2 for git operations, set to false to shell out to git."
diff --git a/src/backend/aqua.rs b/src/backend/aqua.rs
index 3954caf497..714d2d94b1 100644
--- a/src/backend/aqua.rs
+++ b/src/backend/aqua.rs
@@ -508,10 +508,7 @@ impl Backend for AquaBackend {
 
         let paths = cache
             .get_or_try_init_async(async || {
-                let pkg = AQUA_REGISTRY
-                    .package_with_version(&self.id, &[&tv.version])
-                    .await?;
-                let pkg = Self::apply_var_options(pkg, &request_options)?;
+                let pkg = self.package_with_options(tv, &[&tv.version]).await?;
 
                 let srcs = self.srcs(&pkg, tv)?;
                 let paths = if srcs.is_empty() {
@@ -577,15 +574,7 @@ impl Backend for AquaBackend {
         tv: &ToolVersion,
         target: &PlatformTarget,
     ) -> Result<PlatformInfo> {
-        // Map Platform to Aqua's os/arch conventions
-        let target_os = match target.os_name() {
-            "macos" => "darwin",
-            other => other,
-        };
-        let target_arch = match target.arch_name() {
-            "x64" => "amd64",
-            other => other,
-        };
+        let (target_os, target_arch) = Self::to_aqua_platform(target);
 
         // Get version tag
         let tag = match self.get_version_tags().await {
@@ -620,8 +609,9 @@ impl Backend for AquaBackend {
         // platform first, which can leak host-specific overrides into cross-platform lock.
         let pkg = AQUA_REGISTRY.package(&self.id).await?;
         let opts = tv.request.options();
-        let pkg =
-            Self::apply_var_options(pkg.with_version(&versions, target_os, target_arch), &opts)?;
+        let pkg = pkg.with_version(&versions, target_os, target_arch);
+        let pkg = Self::apply_aqua_libc_replacement(pkg, target_os, Self::target_libc(target));
+        let pkg = Self::apply_var_options(pkg, &opts)?;
 
         // Apply version prefix if present
         if let Some(prefix) = &pkg.version_prefix
@@ -660,7 +650,10 @@ impl Backend for AquaBackend {
                 let mut result = (None, None);
                 for candidate in &candidates {
                     let asset_strs = pkg.asset_strs(candidate, target_os, target_arch)?;
-                    match self.github_release_asset(&pkg, candidate, asset_strs).await {
+                    match self
+                        .github_release_asset_for_target(&pkg, candidate, asset_strs, target)
+                        .await
+                    {
                         Ok((url, digest)) => {
                             v = candidate.to_string();
                             result = (Some(url), digest);
@@ -768,12 +761,61 @@ impl AquaBackend {
         tv: &ToolVersion,
         versions: &[&str],
     ) -> Result<AquaPackage> {
-        let pkg = AQUA_REGISTRY
-            .package_with_version(&self.id, versions)
-            .await?;
+        let target = PlatformTarget::from_current();
+        let (target_os, target_arch) = Self::to_aqua_platform(&target);
+        let pkg = AQUA_REGISTRY.package(&self.id).await?;
+        let pkg = pkg.with_version(versions, target_os, target_arch);
+        let pkg = Self::apply_aqua_libc_replacement(pkg, target_os, Self::target_libc(&target));
         Self::apply_var_options(pkg, &tv.request.options())
     }
 
+    fn to_aqua_platform(target: &PlatformTarget) -> (&str, &str) {
+        let target_os = match target.os_name() {
+            "macos" => "darwin",
+            other => other,
+        };
+        let target_arch = match target.arch_name() {
+            "x64" => "amd64",
+            other => other,
+        };
+        (target_os, target_arch)
+    }
+
+    fn target_libc(target: &PlatformTarget) -> Option<String> {
+        target.libc().map(str::to_string).or_else(|| {
+            if target.is_current() {
+                Settings::get().libc().map(str::to_string)
+            } else {
+                None
+            }
+        })
+    }
+
+    fn apply_aqua_libc_replacement(
+        mut pkg: AquaPackage,
+        target_os: &str,
+        libc: Option<String>,
+    ) -> AquaPackage {
+        let Some(libc) = libc else {
+            return pkg;
+        };
+        if target_os != "linux" {
+            return pkg;
+        }
+        let Some(linux) = pkg.replacements.get_mut("linux") else {
+            return pkg;
+        };
+        if is_aqua_linux_libc_replacement(linux) {
+            let libc = if libc == "musl" { "musl" } else { "gnu" };
+            let prefix = linux
+                .strip_suffix("-gnu")
+                .or_else(|| linux.strip_suffix("-musl"))
+                .unwrap_or("unknown-linux");
+            *linux = format!("{prefix}-{libc}");
+        }
+        pkg
+    }
+
     fn apply_var_options(pkg: AquaPackage, opts: &ToolVersionOptions) -> Result<AquaPackage> {
         if pkg.vars.is_empty() {
             return Ok(pkg);
@@ -1296,8 +1338,10 @@ impl AquaBackend {
         pkg: &AquaPackage,
         v: &str,
     ) -> Result<(String, Option<String>)> {
+        let target = PlatformTarget::from_current();
         let asset_strs = pkg.asset_strs(v, os(), arch())?;
-        self.github_release_asset(pkg, v, asset_strs).await
+        self.github_release_asset_for_target(pkg, v, asset_strs, &target)
+            .await
     }
 
     async fn github_release_asset(
@@ -1305,18 +1349,39 @@ impl AquaBackend {
         pkg: &AquaPackage,
         v: &str,
         asset_strs: IndexSet<String>,
+    ) -> Result<(String, Option<String>)> {
+        self.github_release_asset_matching(pkg, v, asset_strs, false)
+            .await
+    }
+
+    async fn github_release_asset_for_target(
+        &self,
+        pkg: &AquaPackage,
+        v: &str,
+        asset_strs: IndexSet<String>,
+        target: &PlatformTarget,
+    ) -> Result<(String, Option<String>)> {
+        // TODO: remove this when aqua supports musl variants natively.
+        // For now aqua templates only see linux/amd64 or linux/arm64, so a
+        // linux-*-musl lock target would otherwise choose the glibc asset even
+        // when a release also publishes the same asset name with an added musl
+        // token.
+        self.github_release_asset_matching(pkg, v, asset_strs, target_prefers_musl(target))
+            .await
+    }
+
+    async fn github_release_asset_matching(
+        &self,
+        pkg: &AquaPackage,
+        v: &str,
+        asset_strs: IndexSet<String>,
+        prefer_musl: bool,
     ) -> Result<(String, Option<String>)> {
         let gh_id = format!("{}/{}", pkg.repo_owner, pkg.repo_name);
         let gh_release = github::get_release(&gh_id, v).await?;
 
         // Prioritize order of asset_strs
-        let asset = asset_strs
-            .iter()
-            .find_map(|expected| {
-                gh_release.assets.iter().find(|a| {
-                    a.name == *expected || a.name.to_lowercase() == expected.to_lowercase()
-                })
-            })
+        let asset = select_github_release_asset(&gh_release.assets, &asset_strs, prefer_musl)
             .wrap_err_with(|| {
                 format!(
                     "no asset found: {}\nAvailable assets:\n{}",
@@ -2430,6 +2495,68 @@ fn is_platform_supported(supported_envs: &[String], os: &str, arch: &str) -> boo
     !envs.is_disjoint(&myself)
 }
 
+fn target_prefers_musl(target: &PlatformTarget) -> bool {
+    target.os_name() == "linux" && AquaBackend::target_libc(target).as_deref() == Some("musl")
+}
+
+fn is_aqua_linux_libc_replacement(replacement: &str) -> bool {
+    matches!(
+        replacement,
+        "unknown-linux-gnu" | "unknown-linux-musl" | "linux-gnu" | "linux-musl"
+    )
+}
+
+fn select_github_release_asset<'a>(
+    assets: &'a [github::GithubAsset],
+    asset_strs: &IndexSet<String>,
+    prefer_musl: bool,
+) -> Option<&'a github::GithubAsset> {
+    let assets_with_tokens = if prefer_musl {
+        assets
+            .iter()
+            .map(|asset| (asset, asset_name_tokens(&asset.name)))
+            .collect_vec()
+    } else {
+        vec![]
+    };
+    asset_strs.iter().find_map(|expected| {
+        let exact = assets
+            .iter()
+            .find(|a| a.name == *expected || a.name.to_lowercase() == expected.to_lowercase());
+
+        let expected_tokens = asset_name_tokens(expected);
+        if prefer_musl
+            && let Some(musl_asset) = assets_with_tokens.iter().find_map(|(asset, tokens)| {
+                is_musl_variant_of_expected_asset(tokens, &expected_tokens).then_some(*asset)
+            })
+        {
+            return Some(musl_asset);
+        }
+
+        exact
+    })
+}
+
+fn is_musl_variant_of_expected_asset(asset_tokens: &[String], expected_tokens: &[String]) -> bool {
+    asset_tokens.iter().any(|token| token == "musl")
+        && !expected_tokens.iter().any(|token| token == "musl")
+        && itertools::equal(
+            asset_tokens
+                .iter()
+                .filter(|token| !matches!(token.as_str(), "musl" | "gnu" | "glibc")),
+            expected_tokens
+                .iter()
+                .filter(|token| !matches!(token.as_str(), "musl" | "gnu" | "glibc")),
+        )
+}
+
+fn asset_name_tokens(name: &str) -> Vec<String> {
+    name.split(|c: char| !c.is_ascii_alphanumeric())
+        .filter(|token| !token.is_empty())
+        .map(|token| token.to_lowercase())
+        .collect()
+}
+
 pub fn os() -> &'static str {
     if cfg!(target_os = "macos") {
         "darwin"
@@ -2452,6 +2579,10 @@ pub fn arch() -> &'static str {
 
 #[cfg(test)]
 mod lock_candidate_tests {
+    use crate::github::GithubAsset;
+
+    use super::*;
+
     fn build_lock_candidates(
         version: &str,
         tag: Option<&str>,
@@ -2495,4 +2626,102 @@ mod lock_candidate_tests {
         assert_eq!(v, "jq-1.7.1");
         assert_eq!(candidates, vec!["jq-v1.7.1", "jq-1.7.1"]);
     }
+
+    fn asset(name: &str) -> GithubAsset {
+        GithubAsset {
+            name: name.to_string(),
+            browser_download_url: format!("https://example.com/{name}"),
+            url: format!("https://api.example.com/{name}"),
+            digest: None,
+        }
+    }
+
+    #[test]
+    fn test_select_github_release_asset_prefers_musl_variant() {
+        let assets = vec![
+            asset("tool-1.0.0-x86_64-unknown-linux-gnu.tar.gz"),
+            asset("tool-1.0.0-x86_64-unknown-linux-musl.tar.gz"),
+        ];
+        let asset_strs = IndexSet::from(["tool-1.0.0-x86_64-unknown-linux-gnu.tar.gz".to_string()]);
+
+        let selected = select_github_release_asset(&assets, &asset_strs, true).unwrap();
+
+        assert_eq!(selected.name, "tool-1.0.0-x86_64-unknown-linux-musl.tar.gz");
+    }
+
+    #[test]
+    fn test_select_github_release_asset_keeps_exact_without_musl_preference() {
+        let assets = vec![
+            asset("tool-1.0.0-x86_64-unknown-linux-gnu.tar.gz"),
+            asset("tool-1.0.0-x86_64-unknown-linux-musl.tar.gz"),
+        ];
+        let asset_strs = IndexSet::from(["tool-1.0.0-x86_64-unknown-linux-gnu.tar.gz".to_string()]);
+
+        let selected = select_github_release_asset(&assets, &asset_strs, false).unwrap();
+
+        assert_eq!(selected.name, "tool-1.0.0-x86_64-unknown-linux-gnu.tar.gz");
+    }
+
+    #[test]
+    fn test_select_github_release_asset_uses_musl_when_exact_missing() {
+        let assets = vec![asset("tool-1.0.0-linux-amd64-musl.tar.gz")];
+        let asset_strs = IndexSet::from(["tool-1.0.0-linux-amd64.tar.gz".to_string()]);
+
+        let selected = select_github_release_asset(&assets, &asset_strs, true).unwrap();
+
+        assert_eq!(selected.name, "tool-1.0.0-linux-amd64-musl.tar.gz");
+    }
+
+    #[test]
+    fn test_musl_variant_match_requires_standalone_token() {
+        let asset_tokens = asset_name_tokens("tool-1.0.0-linux-amd64-muslvariant.tar.gz");
+        let expected_tokens = asset_name_tokens("tool-1.0.0-linux-amd64.tar.gz");
+
+        assert!(!is_musl_variant_of_expected_asset(
+            &asset_tokens,
+            &expected_tokens,
+        ));
+    }
+
+    #[test]
+    fn test_apply_aqua_libc_replacement_switches_target_triples() {
+        let mut pkg = AquaPackage::default();
+        pkg.replacements
+            .insert("linux".to_string(), "unknown-linux-gnu".to_string());
+
+        let pkg = AquaBackend::apply_aqua_libc_replacement(pkg, "linux", Some("musl".to_string()));
+
+        assert_eq!(
+            pkg.replacements.get("linux").map(String::as_str),
+            Some("unknown-linux-musl")
+        );
+    }
+
+    #[test]
+    fn test_apply_aqua_libc_replacement_preserves_linux_prefix() {
+        let mut pkg = AquaPackage::default();
+        pkg.replacements
+            .insert("linux".to_string(), "linux-gnu".to_string());
+
+        let pkg = AquaBackend::apply_aqua_libc_replacement(pkg, "linux", Some("musl".to_string()));
+
+        assert_eq!(
+            pkg.replacements.get("linux").map(String::as_str),
+            Some("linux-musl")
+        );
+    }
+
+    #[test]
+    fn test_apply_aqua_libc_replacement_keeps_non_libc_replacements() {
+        let mut pkg = AquaPackage::default();
+        pkg.replacements
+            .insert("linux".to_string(), "Linux".to_string());
+
+        let pkg = AquaBackend::apply_aqua_libc_replacement(pkg, "linux", Some("musl".to_string()));
+
+        assert_eq!(
+            pkg.replacements.get("linux").map(String::as_str),
+            Some("Linux")
+        );
+    }
 }
diff --git a/src/backend/asset_matcher.rs b/src/backend/asset_matcher.rs
index ef35f06478..21765257dc 100644
--- a/src/backend/asset_matcher.rs
+++ b/src/backend/asset_matcher.rs
@@ -71,11 +71,11 @@ impl AssetArch {
 
 impl AssetLibc {
     pub fn matches_target(&self, target: &str) -> bool {
-        match self {
-            AssetLibc::Gnu => target == "gnu",
-            AssetLibc::Musl => target == "musl",
-            AssetLibc::Msvc => target == "msvc",
-        }
+        target.split('-').any(|part| match self {
+            AssetLibc::Gnu => part == "gnu" || part == "glibc",
+            AssetLibc::Musl => part == "musl",
+            AssetLibc::Msvc => part == "msvc",
+        })
     }
 }
 
@@ -1164,6 +1164,15 @@ abc123def456abc123def456abc123def456abc123def456abc123def456abcd  tool-1.0.0-dar
             .pick_from(&assets)
             .unwrap();
         assert_eq!(result.name, "tool-1.0.0-linux-x86_64-gnu.tar.gz");
+
+        // Compound qualifier still carries the libc preference.
+        let platform = Platform::parse("linux-x64-musl-baseline").unwrap();
+        let target = PlatformTarget::new(platform);
+        let result = AssetMatcher::new()
+            .for_target(&target)
+            .pick_from(&assets)
+            .unwrap();
+        assert_eq!(result.name, "tool-1.0.0-linux-x86_64-musl.tar.gz");
     }
 
     #[test]
diff --git a/src/backend/platform_target.rs b/src/backend/platform_target.rs
index 534ad3d6fc..2e5d66bcd8 100644
--- a/src/backend/platform_target.rs
+++ b/src/backend/platform_target.rs
@@ -27,6 +27,10 @@ impl PlatformTarget {
         self.platform.qualifier.as_deref()
     }
 
+    pub fn libc(&self) -> Option<&str> {
+        self.platform.libc()
+    }
+
     pub fn to_key(&self) -> String {
         self.platform.to_key()
     }
@@ -61,9 +65,18 @@ mod tests {
         assert_eq!(target.os_name(), "linux");
         assert_eq!(target.arch_name(), "x64");
         assert_eq!(target.qualifier(), Some("musl"));
+        assert_eq!(target.libc(), Some("musl"));
         assert_eq!(target.to_key(), "linux-x64-musl");
     }
 
+    #[test]
+    fn test_platform_target_with_compound_libc_qualifier() {
+        let platform = Platform::parse("linux-x64-musl-baseline").unwrap();
+        let target = PlatformTarget::new(platform);
+
+        assert_eq!(target.libc(), Some("musl"));
+    }
+
     #[test]
     fn test_from_current() {
         let target = PlatformTarget::from_current();
diff --git a/src/cache.rs b/src/cache.rs
index 1becb5e964..79cd67c571 100644
--- a/src/cache.rs
+++ b/src/cache.rs
@@ -18,6 +18,7 @@ use crate::build_time::built_info;
 use crate::config::Settings;
 use crate::file::{display_path, modified_duration};
 use crate::hash::hash_to_str;
+use crate::platform::Platform;
 use crate::rand::random_string;
 use crate::toolset::env_cache::CachedEnv;
 use crate::{dirs, file};
@@ -46,7 +47,11 @@ impl CacheManagerBuilder {
     pub fn new(cache_file_path: impl AsRef<Path>) -> Self {
         let settings = Settings::get();
         let mut cache_keys = BASE_CACHE_KEYS.clone();
-        cache_keys.extend([settings.os().to_string(), settings.arch().to_string()]);
+        cache_keys.extend([
+            settings.os().to_string(),
+            settings.arch().to_string(),
+            Platform::current().libc().unwrap_or_default().to_string(),
+        ]);
         Self {
             cache_file_path: cache_file_path.as_ref().to_path_buf(),
             cache_keys,
diff --git a/src/config/settings.rs b/src/config/settings.rs
index 92f23b5899..b68004c1fa 100644
--- a/src/config/settings.rs
+++ b/src/config/settings.rs
@@ -704,6 +704,14 @@ impl Settings {
         }
     }
 
+    pub fn libc(&self) -> Option<&str> {
+        match self.libc.as_deref()?.to_ascii_lowercase().as_str() {
+            "glibc" | "gnu" => Some("gnu"),
+            "musl" => Some("musl"),
+            _ => None,
+        }
+    }
+
     pub fn no_config() -> bool {
         *env::MISE_NO_CONFIG
             || !*crate::env::IS_RUNNING_AS_SHIM
diff --git a/src/platform.rs b/src/platform.rs
index 3185c450ce..475e899b0a 100644
--- a/src/platform.rs
+++ b/src/platform.rs
@@ -43,8 +43,13 @@ impl Platform {
     pub fn current() -> Self {
         let settings = Settings::get();
         let os = settings.os().to_string();
-        let qualifier = if os == "linux" && is_musl_system() {
-            Some("musl".to_string())
+        let qualifier = if os == "linux" {
+            match settings.libc() {
+                Some("musl") => Some("musl".to_string()),
+                Some("gnu") => None,
+                _ if is_musl_system() => Some("musl".to_string()),
+                _ => None,
+            }
         } else {
             None
         };
@@ -55,6 +60,17 @@ impl Platform {
         }
     }
 
+    pub fn libc(&self) -> Option<&str> {
+        self.qualifier
+            .as_deref()?
+            .split('-')
+            .find_map(|part| match part {
+                "gnu" | "glibc" => Some("gnu"),
+                "musl" => Some("musl"),
+                _ => None,
+            })
+    }
+
     /// Validate that this platform is supported
     pub fn validate(&self) -> Result<()> {
         // Validate OS
@@ -78,9 +94,9 @@ impl Platform {
         // Validate qualifier if present
         if let Some(qualifier) = &self.qualifier {
             match qualifier.as_str() {
-                "gnu" | "musl" | "msvc" | "baseline" | "musl-baseline" => {}
+                "gnu" | "glibc" | "musl" | "msvc" | "baseline" | "musl-baseline" => {}
                 _ => bail!(
-                    "Unsupported qualifier '{}'. Supported: gnu, musl, msvc, baseline, musl-baseline",
+                    "Unsupported qualifier '{}'. Supported: gnu, glibc, musl, msvc, baseline, musl-baseline",
                     qualifier
                 ),
             }
@@ -193,14 +209,6 @@ impl From<&str> for Platform {
 fn is_musl_system() -> bool {
     use std::sync::LazyLock;
     static IS_MUSL: LazyLock<bool> = LazyLock::new(|| {
-        // Allow explicit override via environment variable (only gnu/musl accepted)
-        if let Ok(val) = std::env::var("MISE_LIBC") {
-            match val.to_lowercase().as_str() {
-                "musl" => return true,
-                "gnu" => return false,
-                _ => {} // invalid value ignored, fall through to runtime detection
-            }
-        }
         // If glibc's dynamic linker exists, this is a glibc system
         for dir in ["/lib", "/lib64"] {
             if has_file_prefix(dir, "ld-linux-") {
@@ -283,6 +291,12 @@ mod tests {
         assert!(Platform::parse("macos-arm64").unwrap().validate().is_ok());
         assert!(Platform::parse("windows-x64").unwrap().validate().is_ok());
         assert!(Platform::parse("linux-x64-gnu").unwrap().validate().is_ok());
+        assert!(
+            Platform::parse("linux-x64-glibc")
+                .unwrap()
+                .validate()
+                .is_ok()
+        );
 
         // Invalid OS
         assert!(Platform::parse("invalid-x64").unwrap().validate().is_err());
diff --git a/src/plugins/core/bun.rs b/src/plugins/core/bun.rs
index 36b7588f91..e31c4ca055 100644
--- a/src/plugins/core/bun.rs
+++ b/src/plugins/core/bun.rs
@@ -331,10 +331,14 @@ impl BunPlugin {
     }
 
     /// Check if we're running on a musl-based system
-    /// This is determined by the binary's compile-time target, since mixing
-    /// glibc and musl binaries on the same system doesn't work anyway
+    /// Respects the global libc setting when configured, otherwise falls back
+    /// to the binary's compile-time target.
     fn is_musl() -> bool {
-        cfg!(target_env = "musl")
+        match Settings::get().libc() {
+            Some("musl") => true,
+            Some("gnu") => false,
+            _ => cfg!(target_env = "musl"),
+        }
     }
 
     /// Get the platform variant suffix for the current system
diff --git a/src/plugins/core/node.rs b/src/plugins/core/node.rs
index f2147c665c..44c37e6ba7 100644
--- a/src/plugins/core/node.rs
+++ b/src/plugins/core/node.rs
@@ -13,6 +13,7 @@ use crate::file::{TarFormat, TarOptions};
 use crate::http::{HTTP, HTTP_FETCH};
 use crate::install_context::InstallContext;
 use crate::lockfile::PlatformInfo;
+use crate::platform::Platform;
 use crate::toolset::{ToolRequest, ToolVersion};
 use crate::ui::progress_report::SingleReport;
 use crate::{env, file, gpg, hash, http, plugins};
@@ -782,12 +783,18 @@ impl NodePlugin {
         let os = Self::map_os(target.os_name());
         let arch = Self::map_arch(target.arch_name());
 
-        // Flavor (like "glibc") only applies to the current Linux platform
-        // Don't apply it to non-current platforms during cross-platform locking
-        if target.is_current()
-            && target.os_name() == "linux"
-            && let Some(flavor) = &settings.node.flavor
-        {
+        // Only Linux has Node flavors. The node-specific flavor is for the
+        // current host; lock targets use their own libc qualifier.
+        let flavor = match (target.os_name(), target.is_current()) {
+            ("linux", true) => settings
+                .node
+                .flavor
+                .as_deref()
+                .or_else(|| target.libc().filter(|libc| *libc == "musl")),
+            ("linux", false) => target.libc().filter(|libc| *libc == "musl"),
+            _ => None,
+        };
+        if let Some(flavor) = flavor {
             return format!("node-v{version}-{os}-{arch}-{flavor}");
         }
         format!("node-v{version}-{os}-{arch}")
@@ -863,7 +870,17 @@ fn arch(settings: &Settings) -> &str {
 
 fn slug(v: &str) -> String {
     let settings = Settings::get();
-    if let Some(flavor) = &settings.node.flavor {
+    let current = Platform::current();
+    let flavor = if current.os == "linux" {
+        settings
+            .node
+            .flavor
+            .as_deref()
+            .or_else(|| current.libc().filter(|libc| *libc == "musl"))
+    } else {
+        None
+    };
+    if let Some(flavor) = flavor {
         format!("node-v{v}-{}-{}-{flavor}", os(), arch(&settings))
     } else {
         format!("node-v{v}-{}-{}", os(), arch(&settings))
diff --git a/src/plugins/core/python.rs b/src/plugins/core/python.rs
index 885e713830..c6f79c4cea 100644
--- a/src/plugins/core/python.rs
+++ b/src/plugins/core/python.rs
@@ -11,6 +11,7 @@ use crate::git::{CloneOptions, Git};
 use crate::http::{HTTP, HTTP_FETCH};
 use crate::install_context::InstallContext;
 use crate::lockfile::{PlatformInfo, ProvenanceType};
+use crate::platform::Platform;
 use crate::toolset::{ToolRequest, ToolVersion, Toolset};
 use crate::ui::progress_report::SingleReport;
 use crate::{Result, lock_file::LockFile};
@@ -885,7 +886,9 @@ fn python_os(settings: &Settings) -> String {
     } else if cfg!(target_os = "macos") {
         "apple-darwin".into()
     } else {
-        ["unknown", built_info::CFG_OS, built_info::CFG_ENV]
+        let current = Platform::current();
+        let libc = current.libc().unwrap_or("gnu");
+        ["unknown", built_info::CFG_OS, libc]
             .iter()
             .filter(|s| !s.is_empty())
             .join("-")
@@ -935,11 +938,11 @@ fn python_precompiled_platform() -> String {
 }
 
 /// Map a PlatformTarget OS to the python-build-standalone OS string.
-fn python_os_for_target(target: &PlatformTarget) -> &'static str {
+fn python_os_for_target(target: &PlatformTarget) -> String {
     match target.os_name() {
-        "macos" => "apple-darwin",
-        "windows" => "pc-windows-msvc",
-        _ => "unknown-linux-gnu",
+        "macos" => "apple-darwin".to_string(),
+        "windows" => "pc-windows-msvc".to_string(),
+        _ => format!("unknown-linux-{}", target.libc().unwrap_or("gnu")),
     }
 }
 
@@ -997,4 +1000,16 @@ mod tests {
         assert_eq!(resolve_python_arch("macos", "arm64"), "aarch64");
         assert_eq!(resolve_python_arch("macos", "x64"), "x86_64");
     }
+
+    #[test]
+    fn test_python_os_for_target_linux_libc() {
+        use crate::backend::platform_target::PlatformTarget;
+        use crate::platform::Platform;
+
+        let target = PlatformTarget::new(Platform::parse("linux-x64").unwrap());
+        assert_eq!(python_os_for_target(&target), "unknown-linux-gnu");
+
+        let target = PlatformTarget::new(Platform::parse("linux-x64-musl").unwrap());
+        assert_eq!(python_os_for_target(&target), "unknown-linux-musl");
+    }
 }
diff --git a/src/plugins/vfox_plugin.rs b/src/plugins/vfox_plugin.rs
index 436bd7320b..91da5e77e1 100644
--- a/src/plugins/vfox_plugin.rs
+++ b/src/plugins/vfox_plugin.rs
@@ -112,7 +112,14 @@ impl VfoxPlugin {
     }
 
     pub fn vfox(&self) -> (Vfox, mpsc::Receiver<String>) {
+        let settings = Settings::get();
+        let env_type = if settings.os() == "linux" {
+            settings.libc().map(str::to_string)
+        } else {
+            None
+        };
         let mut vfox = Vfox::new();
+        vfox.runtime_env_type = env_type;
         vfox.plugin_dir = dirs::PLUGINS.to_path_buf();
         vfox.cache_dir = dirs::CACHE.to_path_buf();
         vfox.download_dir = dirs::DOWNLOADS.to_path_buf();