Dev Notes

Understanding uv sync and dependency conflicts

If you're switching to uv sync, keep in mind that it behaves differently than the standard uv pip workflow. Here is a quick breakdown of what to expect and how to fix common issues.

The Trap: uv sync Resolves Everything

Unlike uv pip compile, which only looks at what you ask for, uv sync attempts to resolve every dependency in your project, including all optional "extras."

Even if you only request specific extras (e.g., uv sync --extra api), uv still checks if the rest of your extras (like deploy) are compatible with your environment. If they conflict, the command will fail.

The Solution: Declaring Conflicts

If you have optional dependencies that are fundamentally incompatible—meaning they aren't meant to be installed together—you can tell uv to ignore those conflicts during the sync process.

Add a conflicts section to your pyproject.toml:

[tool.uv]
conflicts = [
  [
    { extra = "ai" },
    { extra = "deploy" },
  ],
]

The Result

By explicitly declaring that ai and deploy are mutually exclusive, uv sync --extra api --extra ai will now work perfectly. It effectively tells the resolver, "I know these two don't get along; just focus on the ones I actually requested."

Originally published as GitHub Gist #51837dab7bb02c9b5b1c9509693c7d92

social