{"record":{"id":"d88b34eca78ac1d1","repo":"astral-sh/uv","slug":"pass-wheel-explicitly-to-build-a-wheel-from-a","errorCode":null,"errorMessage":"Pass `--wheel` explicitly to build a wheel from a source distribution","messagePattern":"Pass `--wheel` explicitly to build a wheel from a source distribution","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/uv/src/commands/build_frontend.rs","lineNumber":1446,"sourceCode":"    /// Build a wheel from source.\n    Wheel,\n\n    /// Build a source distribution and a wheel from source.\n    SdistAndWheel,\n\n    /// Build a wheel from a source distribution.\n    WheelFromSdist,\n}\n\nimpl BuildPlan {\n    fn determine(source: &AnnotatedSource, sdist: bool, wheel: bool) -> Result<Self> {\n        Ok(match &source.source {\n            Source::File(_) => {\n                // We're building from a file, which must be a source distribution.\n                match (sdist, wheel) {\n                    (false, true) => Self::WheelFromSdist,\n                    (false, false) => {\n                        return Err(anyhow::anyhow!(\n                            \"Pass `--wheel` explicitly to build a wheel from a source distribution\"\n                        ));\n                    }\n                    (true, _) => {\n                        return Err(anyhow::anyhow!(\n                            \"Building an `--sdist` from a source distribution is not supported\"\n                        ));\n                    }\n                }\n            }\n            Source::Directory(_) => {\n                // We're building from a directory.\n                match (sdist, wheel) {\n                    (false, false) => Self::SdistToWheel,\n                    (false, true) => Self::Wheel,\n                    (true, false) => Self::Sdist,\n                    (true, true) => Self::SdistAndWheel,\n                }","sourceCodeStart":1428,"sourceCodeEnd":1464,"githubUrl":"https://github.com/astral-sh/uv/blob/f1a42680ff5272232d65748acf338b19778dde24/crates/uv/src/commands/build_frontend.rs#L1428-L1464","documentation":"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.","triggerScenarios":"`uv build ./dist/mypkg-1.0.tar.gz` with no build-constraint flags; scripts used to directory builds pointed at an archive without flags.","commonSituations":"Rebuilding a wheel from a downloaded sdist (e.g., to add a platform tag or re-sign); verifying an sdist builds in CI.","solutions":["Add `--wheel`: `uv build --wheel ./pkg.tar.gz`.","If you wanted an sdist as output, build from the project directory instead — sdists cannot be produced from sdists."],"exampleFix":"# before\nuv build ./dist/mypkg-1.0.tar.gz\n# after\nuv build --wheel ./dist/mypkg-1.0.tar.gz","handlingStrategy":"validation","validationCode":"# Shell: always be explicit when building from an archive\nif [ -f \"$SRC\" ]; then\n  uv build --wheel \"$SRC\"\nelse\n  uv build \"$SRC\"\nfi","typeGuard":"fn plan_for_file(sdist: bool, wheel: bool) -> Option<BuildPlan> {\n    match (sdist, wheel) {\n        (false, true) => Some(BuildPlan::WheelFromSdist),\n        _ => None, // (false,false) and (true,*) are invalid for file sources\n    }\n}","tryCatchPattern":null,"preventionTips":["Treat 'building from an sdist' as a wheel operation: always pass --wheel.","Remember --sdist is only meaningful when the source is a project directory."],"tags":["build","sdist","wheel","cli-usage"],"backgroundTag":null,"analyzedSha":"f1a42680ff5272232d65748acf338b19778dde24","analyzedAt":"2026-08-16T04:51:47.599Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}