astral-sh/uv · error · anyhow::Error

The file `{}` appears to be a `pylock.toml` file, but overri

Error message

The file `{}` appears to be a `pylock.toml` file, but overrides must be specified in `requirements.txt` format

What it means

Thrown by RequirementsSource::from_overrides_txt (crates/uv-requirements/src/sources.rs:171) when the --overrides path's file name matches a pylock.toml lock file (is_pylock_toml). Overrides must be requirements.txt-format pins; a PEP 751 lock file is a complete resolution input, not an override list, so uv rejects it early.

Source

Thrown at crates/uv-requirements/src/sources.rs:171

        if path == Path::new("-") {
            return Ok(Self::Extensionless(path));
        }

        for file_name in ["pyproject.toml", "setup.py", "setup.cfg"] {
            if path.ends_with(file_name) {
                return Err(anyhow::anyhow!(
                    "The file `{}` appears to be a `{}` file, but overrides must be specified in `requirements.txt` format",
                    path.user_display(),
                    file_name
                ));
            }
        }
        if path
            .file_name()
            .and_then(OsStr::to_str)
            .is_some_and(is_pylock_toml)
        {
            return Err(anyhow::anyhow!(
                "The file `{}` appears to be a `pylock.toml` file, but overrides must be specified in `requirements.txt` format",
                path.user_display(),
            ));
        } else if path
            .extension()
            .is_some_and(|ext| ext.eq_ignore_ascii_case("toml"))
        {
            return Err(anyhow::anyhow!(
                "The file `{}` appears to be a TOML file, but overrides must be specified in `requirements.txt` format",
                path.user_display(),
            ));
        }
        Ok(Self::RequirementsTxt(path))
    }

    /// Parse a [`RequirementsSource`] from a user-provided string, assumed to be a positional
    /// package (e.g., `uv pip install flask`).
    ///

View on GitHub (pinned to f1a42680ff)

Solutions

Write the intended version pins into an overrides.txt (`package==x.y.z` lines) and pass that instead
If you want the exact locked set, install from the lock directly: `uv pip install -r pylock.toml`
Export pins first: `uv export --format requirements-txt -o overrides.txt`

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

fn is_pylock_toml_name(path: &Path) -> bool {
    path.file_name()
        .and_then(std::ffi::OsStr::to_str)
        .is_some_and(|name| name == "pylock.toml" || (name.starts_with("pylock.") && name.ends_with(".toml")))
}

if is_pylock_toml_name(&path) {
    // export pins to overrides.txt instead of passing the lock
}

Try / catch

match RequirementsSource::from_overrides_txt(path) {
    Err(err) if err.to_string().contains("pylock.toml") => {
        // convert lock pins into an overrides.txt and retry
    }
    source => source?,
}

Prevention

Treat --overrides as pins-only input; locks never go there
Name override files explicitly (overrides.txt) and generate them with `uv export`
Add a pre-flight check in wrappers that scans override paths for pylock names

When it happens

Trigger: Running `uv pip install --overrides pylock.toml ...` or passing a pylock.<name>.toml variant; programmatically calling from_overrides_txt with such a file name.

Common situations: Users assume the lock file can be layered as an override on top of a looser requirements.txt; CI pipelines try to force versions by overriding from the lock.

Related errors

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