astral-sh/uv · error

Cannot specify constraints with a `pylock.toml` file

Error message

Cannot specify constraints with a `pylock.toml` file

What it means

Thrown in RequirementsSpecification::from_sources (crates/uv-requirements/src/specification.rs:478) when requirements include a pylock.toml and the constraints list is non-empty. Constraints would narrow a resolution, but a pylock.toml is already fully resolved — there is nothing left to constrain — so any --constraints usage alongside it is rejected.

Source

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

        // 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(..)))
            {
                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"
                        ));

View on GitHub (pinned to f1a42680ff)

Solutions

1. Drop --constraints from the invocation when installing from pylock.toml
2. If the pins matter, incorporate them at lock-creation time (regenerate the lock from the constrained project) instead of at install time
3. Prefer `uv sync` for reproducing a locked environment end-to-end

Example fix

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

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

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

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

When it happens

Trigger: `uv pip install -r pylock.toml --constraints constraints.txt` (constraints list non-empty while a PylockToml source is present in requirements); programmatic from_sources with both populated.

Common situations: Users layering corporate pin files on top of a lock; CI templates that always set --constraints; transitioning from constraints-only workflows to locks without dropping the old flags.

Related errors

• The file `{}` appears to be a `pylock.toml` file, but constr
• Cannot use `{}` as a constraint file
• Cannot specify additional requirements alongside a `pylock.t
• Cannot specify overrides 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/58e0c913c5771b8a. Report an issue: GitHub.