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

The file `{}` appears to be a `{}` file, but overrides must

Error message

The file `{}` appears to be a `{}` 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:159) when the --overrides path ends with pyproject.toml, setup.py, or setup.cfg. Override files must use requirements.txt syntax (lines that replace pinned versions), and Python project metadata files are explicitly blocked so uv does not silently misread them.

Source

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

            .is_some_and(|ext| ext.eq_ignore_ascii_case("toml"))
        {
            return Err(anyhow::anyhow!(
                "The file `{}` appears to be a TOML file, but constraints must be specified in `requirements.txt` format",
                path.user_display(),
            ));
        }
        Ok(Self::RequirementsTxt(path))
    }

    /// Parse a [`RequirementsSource`] from an `overrides.txt` file.
    pub fn from_overrides_txt(path: PathBuf) -> Result<Self> {
        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"))

View on GitHub (pinned to f1a42680ff)

Solutions

  1. Create an overrides.txt with the replacement pins (`package==1.2.3` per line) and pass that via --overrides
  2. To change a dependency of the current project, edit the pyproject.toml dependency table instead of using --overrides
  3. To override versions resolved from another project, extract its dependencies to a .txt file first (e.g. `uv export`)

Example fix

# before
uv pip install -r requirements.txt --overrides pyproject.toml
# after
# overrides.txt: `flask==3.0.0`
uv pip install -r requirements.txt --overrides overrides.txt
Defensive patterns

Strategy: validation

Validate before calling

fn overrides_path_ok(path: &Path) -> bool {
    path == Path::new("-")
        || !["pyproject.toml", "setup.py", "setup.cfg"]
            .iter()
            .any(|name| path.ends_with(name))
}

if !overrides_path_ok(&path) {
    return Err(anyhow::anyhow!("{path:?} is project metadata; write overrides to a .txt file"));
}

Try / catch

match RequirementsSource::from_overrides_txt(path) {
    Err(err) if err.to_string().contains("overrides must be specified in `requirements.txt` format") => {
        // skip or substitute an overrides.txt
    }
    source => source?,
}

Prevention

When it happens

Trigger: Running `uv pip install --overrides pyproject.toml ...` (or a path ending in setup.py / setup.cfg), or calling from_overrides_txt with such a path; the check uses Path::ends_with so nested paths like ./sub/pyproject.toml also match.

Common situations: Users coming from pip's `--constraint pyproject.toml` habits apply it to --overrides; monorepo scripts glob all pyproject.toml files into an overrides list; users try to override versions declared in their own project metadata.

Related errors

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