astral-sh/uv · error

Cannot specify `--package` when building from a file

Error message

Cannot specify `--package` when building from a file

What it means

`uv build --package <name>` narrows a workspace build to one member, which only makes sense when the source is a directory. If the resolved source is a file (a sdist archive), uv rejects the combination because --package cannot select inside an archive. The check is a direct Source::File match before workspace lookup.

Source

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

    // Limit to the stable version range.
    let min_version = Version::from_str(uv_version::version()).unwrap();
    debug_assert!(
        min_version.release()[0] == 0,
        "migrate to major version bumps"
    );
    let max_version = Version::new(
        [0, min_version.release()[1] + 1]
            .into_iter()
            // Add trailing zeroes to match the version length, to use the same style
            // as `--bounds`.
            .chain(iter::repeat_n(0, min_version.release().len() - 2)),
    );

    // If a `--package` or `--all-packages` was provided, adjust the source directory.
    let packages = if let Some(package) = package {
        if matches!(src, Source::File(_)) {
            return Err(anyhow::anyhow!(
                "Cannot specify `--package` when building from a file"
            ));
        }

        let workspace = match workspace {
            Ok(ref workspace) => workspace,
            Err(err) => {
                return Err(err).context("`--package` was provided, but no workspace was found");
            }
        };

        let package = workspace
            .packages()
            .get(package)
            .ok_or_else(|| anyhow::anyhow!("Package `{package}` not found in workspace"))?;

        if !package.pyproject_toml().is_package(true) {
            let name = &package.project().name;

View on GitHub (pinned to f1a42680ff)

Solutions

1. Drop `--package` when building from a file: the archive already identifies the package.
2. Or point the source at the package directory (and keep --package) instead of the built archive.

Example fix

# before
uv build --package mypkg ./dist/mypkg-1.0.tar.gz
# after
uv build ./dist/mypkg-1.0.tar.gz      # or: uv build --package mypkg ./crates/mypkg

# Shell: only add --package when the source is a directory
if [ -d "$SRC" ]; then
  uv build --package "$PKG" "$SRC"
else
  uv build "$SRC"
fi

fn supports_package_selection(src: &Source) -> bool {
    matches!(src, Source::Directory(_))
}

When it happens

Trigger: `uv build --package mypkg ./dist/mypkg-1.0.tar.gz`; passing a .tar.gz/.zip as src while --package is set via CLI or config; scripts that always pass --package accidentally reusing a path that now points at a file.

Common situations: A build script shared between directory builds and artifact rebuilds; flags copy-pasted from a workspace invocation into an sdist rebuild command.

Related errors

• Cannot specify `--all-packages` when building from a file
• Package `{package}` not found in workspace
• Package `{}` is missing a `{}`. For example, to build with `
• Pass `--wheel` explicitly to build a wheel from a source dis
• Building an `--sdist` from a source distribution is not supp

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