# Databricks serverless jobs from pyproject.toml, and the uv.lock beside it

> Databricks serverless job tasks can now read their environment from pyproject.toml, in Beta. Why we would treat uv.lock as part of the job.

By Tyler Harker, 23 October 2026. Databricks Field Guide, TechFabric. Canonical: https://databricks.techfabric.com/notes/serverless-job-environments-from-pyproject-toml-beta/

For a serverless Python job, we'd make a missing lockfile a deployment failure. Databricks' [22 October 2026 Beta release](https://docs.databricks.com/aws/en/release-notes/product/2026/october#serverless-job-environments-from-pyprojecttoml-beta) lets notebook and Python script tasks read their environment from `pyproject.toml`, but it doesn't make the lockfile mandatory at runtime.

That distinction changes the CI check. A green task can mean that the runtime resolved a fresh set of dependencies. Sharing one dependency definition is worth pursuing, but when a release can resolve versions after review, the reviewer has approved a range of possible environments whose behavior may change between otherwise identical deployments. We'd reject that for a controlled deployment.

## A green run isn't proof of a locked install

The [project-environment documentation](https://docs.databricks.com/aws/en/compute/serverless/dependencies#project-environment) describes a fallback to `uv pip install -r pyproject.toml` when `uv.lock` is missing or stale. It resolves dependencies without enforcing the lock and doesn't install the project package itself.

So the first change belongs before [bundle deployment](https://databricks.techfabric.com/guide/ci-cd/), in the project directory:

```bash
uv lock --check && databricks bundle deploy
```

Databricks documents `uv lock --check`; putting it before deployment is our recommendation. Don't run `uv lock` automatically in the release step to repair a failure. That would move the dependency decision from review into deployment.

Here's the development trial we'd use. We haven't run these acceptance cases on a job:

| Change in a disposable checkout | Required outcome before deployment |
| --- | --- |
| Keep the reviewed project and current lock | The lock check passes; the task must still pass its tests |
| Remove `uv.lock` | Stop without deploying |
| Change a dependency so the lock is stale | Stop without deploying |
| Regenerate the lock deliberately and review its diff | Retry the normal checked deployment |

The negative cases matter most. If either reaches a running task, the deployment path hasn't enforced the rule, even when that particular run happens to choose the expected versions.

```mermaid Where we would reject an unreviewed dependency resolution
flowchart LR
  A["Project and committed uv.lock"] --> B{"uv lock --check passes"}
  B -->|"No"| C["Stop before deployment"]
  B -->|"Yes"| D["Deploy the project environment"]
  D --> E["Check installed versions in a trial task"]
```

## Keep packaging out of the first change

Keep the existing wheel build and bundle `artifacts` mapping unchanged during the dependency trial. Otherwise, a failed import could come from a packaging change or an environment change, and the trial would no longer isolate the decision.

Our proposed review would compare the deployable files with the reviewed checkout, since a lock check in a developer's directory says nothing about a release that ships a different project definition or omits the lock beside it. Run the check against the files being deployed and keep their revision with the job's test result.

There's a cost to that choice: a dependency update now needs a reviewed lock change, even when the runtime would have recovered by resolving it. We'd accept that extra review to keep each deployed environment tied to a release.

We haven't tried this Beta on our jobs. Check the [environment and packaging prerequisites](https://docs.databricks.com/aws/en/compute/serverless/dependencies#project-environment) before selecting a development target. Then have the release owner demonstrate that both failing-lock cases stop deployment. Until they do, keep the existing job definition.