Skip to content


Configuration

uv-ship reads user defined settings from a [tool.uv-ship] table in a toml file. By default, it will look for such a table in either uv-ship.toml or pyproject.toml in your project root. Optionally, you can use the --config flag to point to a custom file.

the config source is reported every time you invoke uv-ship 
$ uv-ship

uv-ship - a CLI-tool for shipping with uv
config source: "pyproject.toml"

If no config is provided, uv-ship will fall back to its default settings.

Example Configuration

# pyproject.toml
[tool.uv-ship]
release-branch = "main"
tag-prefix = "v"
allow-dirty = false
changelog-path = "CHANGELOG"
changelog-template = "- {message} [{hash}]"

Note

If both uv-ship.toml and pyproject.toml contain a [tool.uv-ship] table, the CLI aborts to avoid ambiguous settings.


Available Settings

release-branch

string | bool : "main"

Defines the branch that must be checked out before shipping. Set to false to disable this check.

tag-prefix

string : "v"

Prefix added to the Git tag (e.g. 1.6.2 becomes v1.6.2).

allow-dirty

bool : false

Allow preflight checks to pass despite uncommitted changes. You can override per-run with --dirty

changelog-path

string : "CHANGELOG"

Relative path to the changelog file that the changelog feature reads and refreshes.

changelog-template

string : "- {message} [{commit_ref}]"

Template used when rendering commit entries in the changelog preview.
The tokens below are supported placeholders:

  • {message} – the commit subject line.
  • {commit_ref} – a Markdown link to the commit
  • {commit_hash}/{hash} – the short commit hash.
  • {repo_url} – the base commit URL

If uv-ship cannot resolve the repo_url it will fall back to commit hash instead.
(applies to commit_ref and repo_url tokens)

The default produces following format:

  • feat: add changelog template [c505b40]

unreleased-tag

string : "[unreleased]"

The default tag used by uv-ship log for all commits since the latest tag.

repo-url

string : ""

Option for overriding the repository URL in case it is a private (eg: self-hosted organization repositories)

commit-message

string : "new version {old_ver} → {new_ver}"

Template for the commit message that is generated. It accepts two optional tokens, {old_ver} and {new_ver}, which will represent the package version before and after uv-ship completes, respectively.

For example, this is a message generated by the default setting:

new version 1.6.2 → 1.7.0

dry-run

bool : false

Force all commands into dry-run mode. May be convenient when testing the tool, but can't be overridden in in the CLI and thus needs to be set to false for operation.