`uv sync {lock_check}` requires a script lockfile; run `{}`

Error message

`uv sync {lock_check}` requires a script lockfile; run `{}` to lock the script

What it means

Error "`uv sync {lock_check}` requires a script lockfile; run `{}` to lock the script" thrown in astral-sh/uv.

Source

Thrown at crates/uv/src/commands/project/sync.rs:237

    // Show the intermediate results if relevant
    if let Some(message) = sync_report.format(output_format) {
        writeln!(printer.stderr(), "{message}")?;
    }

    // Special-case: we're syncing a script that doesn't have an associated lockfile. In that case,
    // we don't create a lockfile, so the resolve-and-install semantics are different.
    if let SyncTarget::Script(script) = &target {
        let lockfile = LockTarget::from(script).lock_path();
        if !lockfile.is_file() {
            if frozen.is_some() {
                return Err(anyhow::anyhow!(
                    "`uv sync --frozen` requires a script lockfile; run `{}` to lock the script",
                    format!("uv lock --script {}", script.path.user_display()).green(),
                ));
            }

            if let LockCheck::Enabled(lock_check) = lock_check {
                return Err(anyhow::anyhow!(
                    "`uv sync {lock_check}` requires a script lockfile; run `{}` to lock the script",
                    format!("uv lock --script {}", script.path.user_display()).green(),
                ));
            }

            // Parse the requirements from the script.
            let spec = script_specification(
                script.into(),
                &settings.resolver,
                cache,
                workspace_cache,
                client_builder.credentials_cache(),
            )
            .await?
            .unwrap_or_default();
            let script_extra_build_requires = script_extra_build_requires(
                script.into(),
                &settings.resolver,

View on GitHub (pinned to f1a42680ff)

When it happens

Trigger: Thrown at crates/uv/src/commands/project/sync.rs:237 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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