astral-sh/uv · error

Cannot use `{}` as an exclude file

Error message

Cannot use `{}` as an exclude file

What it means

Thrown in RequirementsSpecification::from_sources (crates/uv-requirements/src/specification.rs:454) when the excludes list contains a RequirementsSource::PylockToml variant. Exclusion sources mark packages to drop from resolution; a PEP 751 lock file cannot serve that role, so uv refuses it while assembling the combined specification.

Source

Thrown at crates/uv-requirements/src/specification.rs:454

            } else {
                None
            }
        }) {
            return Err(anyhow::anyhow!(
                "Cannot use `{}` as an override file",
                pylock_toml.user_display()
            ));
        }

        // Disallow `pylock.toml` files as excludes.
        if let Some(pylock_toml) = excludes.iter().find_map(|source| {
            if let RequirementsSource::PylockToml(path) = source {
                Some(path)
            } else {
                None
            }
        }) {
            return Err(anyhow::anyhow!(
                "Cannot use `{}` as an exclude file",
                pylock_toml.user_display()
            ));
        }

        // If we have a `pylock.toml`, don't allow additional requirements, constraints, or
        // overrides.
        if let Some(pylock_toml) = requirements.iter().find_map(|source| {
            if let RequirementsSource::PylockToml(path) = source {
                Some(path)
            } else {
                None
            }
        }) {
            if requirements
                .iter()
                .any(|source| !matches!(source, RequirementsSource::PylockToml(..)))
            {

View on GitHub (pinned to f1a42680ff)

Solutions

1. Remove the pylock.toml from the excludes list
2. Express exclusions as a requirements.txt-style file listing package names to exclude
3. If you meant to constrain resolution to the lock, see errors 53/57 for the supported patterns

Example fix

# before (programmatic)
excludes: vec![RequirementsSource::PylockToml(lock.into())],
// after
excludes: vec![RequirementsSource::RequirementsTxt(excl.into())],

let bad = excludes.iter().any(|s| matches!(s, RequirementsSource::PylockToml(_)));
if bad {
    return Err(anyhow::anyhow!("refusing to assemble spec: pylock.toml is not an exclude source"));
}

fn is_pylock_source(s: &RequirementsSource) -> bool {
    matches!(s, RequirementsSource::PylockToml(_))
}

match RequirementsSpecification::from_sources(/* .. */).await {
    Err(err) if err.to_string().contains("as an exclude file") => {
        // drop the pylock entry and reassemble
    }
    spec => spec?,
}

When it happens

Trigger: Programmatic from_sources invocation with a PylockToml source in the excludes Vec; a CLI flow that resolved an exclusion path to a pylock source before this constructor; only the first offending file is reported.

Common situations: Tooling that passes lock files into every source slot uniformly; misconfigured exclude lists built from directory globs.

Related errors

• Cannot use `{}` as a constraint file
• Cannot use `{}` as an override file
• Cannot specify additional requirements alongside a `pylock.t
• Cannot specify constraints with a `pylock.toml` file
• Cannot specify overrides with a `pylock.toml` file

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