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

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

Error message

The file `{}` appears to be a 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:179) when the --overrides path has a .toml extension (case-insensitive) that is not one of the specially-handled project files. Override files must be requirements.txt-format, so any generic TOML is rejected before parsing.

Source

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

                    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`).
    ///
    /// If the user provided a value that appears to be a `requirements.txt` file or a local
    /// directory, prompt them to correct it (if the terminal is interactive).
    pub fn from_package_argument(name: &str) -> Result<Self> {
        // If the user provided a `requirements.txt` file without `-r` (as in
        // `uv pip install requirements.txt`), prompt them to correct it.
        #[expect(clippy::case_sensitive_file_extension_comparisons)]
        if (name.ends_with(".txt") || name.ends_with(".in")) && Path::new(&name).is_file() {
            let term = Term::stderr();

View on GitHub (pinned to f1a42680ff)

Solutions

  1. Rename/convert the file to overrides.txt with one `package==version` pin per line
  2. If the TOML holds pins under a table, flatten that table into plain requirement lines
  3. Verify the path — the intended .txt overrides file may have been misnamed

Example fix

# before
uv pip install -r requirements.txt --overrides overrides.toml
# after
# overrides.txt: `urllib3==2.2.1`
uv pip install -r requirements.txt --overrides overrides.txt
Defensive patterns

Strategy: validation

Validate before calling

fn overrides_extension_ok(path: &Path) -> bool {
    path == Path::new("-")
        || path
            .extension()
            .map(|ext| !ext.eq_ignore_ascii_case("toml"))
            .unwrap_or(true)
}

if !overrides_extension_ok(&path) {
    return Err(anyhow::anyhow!("{path:?}: overrides must be requirements.txt format"));
}

Try / catch

match RequirementsSource::from_overrides_txt(path) {
    Err(err) if err.to_string().contains("appears to be a TOML file") => {
        // flatten the TOML pins into overrides.txt and retry
    }
    source => source?,
}

Prevention

When it happens

Trigger: Running `uv pip install --overrides overrides.toml` or `--overrides pinned.TOML`; any from_overrides_txt call whose path extension equals toml ignoring ASCII case.

Common situations: Users version their override pins in TOML from other tooling (Poetry/Hatch config, custom manifests) and pass them to uv unchanged; typos where overrides.txt was saved as .toml.

Related errors

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