astral-sh/uv · error

Pass `--wheel` explicitly to build a wheel from a source dis

Error message

Pass `--wheel` explicitly to build a wheel from a source distribution

What it means

In BuildPlan::determine, when the source is a file it must be a source distribution; building an sdist into a wheel is a destructive one-way operation, so uv requires an explicit `--wheel` flag rather than defaulting. With (sdist=false, wheel=false) on a file source, this error tells you to opt in. The (false, true) case maps to WheelFromSdist.

Source

Thrown at crates/uv/src/commands/build_frontend.rs:1446

    /// Build a wheel from source.
    Wheel,

    /// Build a source distribution and a wheel from source.
    SdistAndWheel,

    /// Build a wheel from a source distribution.
    WheelFromSdist,
}

impl BuildPlan {
    fn determine(source: &AnnotatedSource, sdist: bool, wheel: bool) -> Result<Self> {
        Ok(match &source.source {
            Source::File(_) => {
                // We're building from a file, which must be a source distribution.
                match (sdist, wheel) {
                    (false, true) => Self::WheelFromSdist,
                    (false, false) => {
                        return Err(anyhow::anyhow!(
                            "Pass `--wheel` explicitly to build a wheel from a source distribution"
                        ));
                    }
                    (true, _) => {
                        return Err(anyhow::anyhow!(
                            "Building an `--sdist` from a source distribution is not supported"
                        ));
                    }
                }
            }
            Source::Directory(_) => {
                // We're building from a directory.
                match (sdist, wheel) {
                    (false, false) => Self::SdistToWheel,
                    (false, true) => Self::Wheel,
                    (true, false) => Self::Sdist,
                    (true, true) => Self::SdistAndWheel,
                }

View on GitHub (pinned to f1a42680ff)

Solutions

1. Add `--wheel`: `uv build --wheel ./pkg.tar.gz`.
2. If you wanted an sdist as output, build from the project directory instead — sdists cannot be produced from sdists.

Example fix

# before
uv build ./dist/mypkg-1.0.tar.gz
# after
uv build --wheel ./dist/mypkg-1.0.tar.gz

# Shell: always be explicit when building from an archive
if [ -f "$SRC" ]; then
  uv build --wheel "$SRC"
else
  uv build "$SRC"
fi

fn plan_for_file(sdist: bool, wheel: bool) -> Option<BuildPlan> {
    match (sdist, wheel) {
        (false, true) => Some(BuildPlan::WheelFromSdist),
        _ => None, // (false,false) and (true,*) are invalid for file sources
    }
}

When it happens

Trigger: `uv build ./dist/mypkg-1.0.tar.gz` with no build-constraint flags; scripts used to directory builds pointed at an archive without flags.

Common situations: Rebuilding a wheel from a downloaded sdist (e.g., to add a platform tag or re-sign); verifying an sdist builds in CI.

Related errors

• Building an `--sdist` from a source distribution is not supp
• Cannot specify `--package` when building from a file
• Cannot specify `--all-packages` when building from a file
• Source `{}` does not exist
• Package `{package}` not found in workspace

AI-assisted analysis of astral-sh/uv@f1a42680ff (2026-08-16). Data as JSON: /api/errors/d88b34eca78ac1d1. Report an issue: GitHub.