Add --frozen flag to "sync-and-running" documentation

[f0lie]

https://docs.astral.sh/uv/guides/integration/github/#syncing-and-running

We have:

name: Example

jobs:
  uv-example:
    name: python
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v5

      - name: Install the project
        run: uv sync --all-extras --dev

      - name: Run tests
        # For example, using `pytest`
        run: uv run pytest tests

And it seems like it should be:

name: Example

jobs:
  uv-example:
    name: python
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v5

      - name: Install the project
        run: uv sync --all-extras --dev --frozen

      - name: Run tests
        # For example, using `pytest`
        run: uv run pytest tests

There should also be in the docs a blurb about how by default uv sync updates all the lockfile and using --frozen ensures that the same version of the packages on the dev machine is used by the github actions VM.

This behavior isn't very obvious for a newcomer reading the documentation and the integration section would be a great place to clarify that behavior.

[konstin]

I think we should add this, though as --locked instead of --frozen to assert that the lockfile is up-to-date.

[johnthagen]

I noticed this too at

• https://docs.astral.sh/uv/guides/integration/github/#syncing-and-running

Also reading the docs, the distinction between --frozen and --locked is a bit difficult to understand.

Also, in the Docker docs, --frozen is used rather than --locked:

https://docs.astral.sh/uv/guides/integration/docker/#installing-a-project

It seems like the user would normally want --locked to avoid the situation

Other Thought

I was also pretty surprised that --locked wasn't the default for uv sync. To me when someone comes to a project, whether a new developer, a CI environment, a container image etc, to me enforcing consistency of dependencies by defaul with uv sync seems like the most ideal situation?

[zanieb]

We might want to add a note on --frozen in https://docs.astral.sh/uv/concepts/projects/sync/#checking-if-the-lockfile-is-up-to-date or add a section to https://docs.astral.sh/uv/concepts/projects/sync/#syncing-the-environment

--frozen is used in the Docker example because we're using the uv.lock as the source of truth there. --locked may be a better option for people to avoid surprises.

was also pretty surprised that --locked wasn't the default for uv sync. To me when someone comes to a project, whether a new developer, a CI environment, a container image etc, to me enforcing consistency of dependencies by defaul with uv sync seems like the most ideal situation?

We're focusing on the development experience here which is that uv sync and uv run here should "just do what they're supposed to" not throw an error if you have modified your pyproject.toml. This is the same thing that Cargo does. In contrast, the deployment experience is more of a "write it once" thing and it's reasonable to opt-in to additional safeguards.

[johnthagen]

@zanieb I'm sympathetic to your goals, and agree they are at odds with what I suggest in

• Have uv sync default to --locked #12372

I can concede the tradeoffs you're making and if Cargo works this way that is extra support to your position.

I still feel unsure of this myself given the potential for an unexpected footgun, but can respect the decision you all are making.