astral-sh/uv · error

Cannot specify overrides with a `pylock.toml` file

Error message

Cannot specify overrides with a `pylock.toml` file

What it means

Thrown in RequirementsSpecification::from_sources (crates/uv-requirements/src/specification.rs:483) when requirements include a pylock.toml and the overrides list is non-empty. Overrides rewrite version constraints during resolution, but a lock file's versions are already fixed, so applying overrides is meaningless and rejected.

Source

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

            } else {
                None
            }
        }) {
            if requirements
                .iter()
                .any(|source| !matches!(source, RequirementsSource::PylockToml(..)))
            {
                return Err(anyhow::anyhow!(
                    "Cannot specify additional requirements alongside a `pylock.toml` file",
                ));
            }
            if !constraints.is_empty() {
                return Err(anyhow::anyhow!(
                    "Cannot specify constraints with a `pylock.toml` file"
                ));
            }
            if !overrides.is_empty() {
                return Err(anyhow::anyhow!(
                    "Cannot specify overrides with a `pylock.toml` file"
                ));
            }

            // If we have a `pylock.toml`, disallow specifying paths for groups; instead, require
            // that all groups refer to the `pylock.toml` file.
            if let Some(groups) = groups {
                let mut names = Vec::new();
                for group in &groups.groups {
                    if group.path.is_some() {
                        return Err(anyhow::anyhow!(
                            "Cannot specify paths for groups with a `pylock.toml` file; all groups must refer to the `pylock.toml` file"
                        ));
                    }
                    names.push(group.name.clone());
                }

                if !names.is_empty() {

View on GitHub (pinned to f1a42680ff)

Solutions

1. Remove --overrides when installing from pylock.toml
2. Bake the forced versions into the lock: update the source project with the pinned versions and re-export the lock
3. For upgrading a locked environment, regenerate the lock rather than overriding at install time

Example fix

# before
uv pip install -r pylock.toml --overrides overrides.txt
# after
uv pip install -r pylock.toml

let has_pylock = requirements.iter().any(|s| matches!(s, RequirementsSource::PylockToml(_)));
if has_pylock && !overrides.is_empty() {
    return Err(anyhow::anyhow!("overrides are not applicable alongside a pylock.toml"));
}

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

match RequirementsSpecification::from_sources(requirements, constraints, overrides, /* .. */).await {
    Err(err) if err.to_string().contains("Cannot specify overrides with a `pylock.toml`") => {
        // clear the overrides list and retry
    }
    spec => spec?,
}

When it happens

Trigger: `uv pip install -r pylock.toml --overrides overrides.txt`; programmatic from_sources with a PylockToml requirement plus a populated overrides Vec.

Common situations: Security-patch pipelines that force versions via overrides meeting locked installs; leftover --overrides flags in scripts after switching to pylock.toml.

Related errors

• The file `{}` appears to be a `pylock.toml` file, but overri
• Cannot use `{}` as an override file
• Cannot specify additional requirements alongside a `pylock.t
• Cannot specify constraints with a `pylock.toml` file
• Cannot specify paths for groups with a `pylock.toml` file; a

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