poetry-publish

Publish the current package to PyPI

$ poetry publish

$ poetry publish --build

$ poetry publish [[-r|--repository]] [repository_name]

$ poetry publish [[-u|--username]] [username] [[-p|--password]] [password]

$ poetry publish --dry-run

$ poetry publish --skip-existing

poetry publish [options]

--build
    Build the package (wheel & sdist) before publishing.

--dry-run
    Perform all steps except the actual upload.

--skip-existing
    Ignore errors for files that already exist on the remote.

--repository
    Publish to the repository configured under in pyproject.toml.

--username
    Username for repository authentication (overrides stored credentials).

--password
    Password or token for repository authentication.

--cert
    Path to a client SSL certificate file.

--client-cert
    Path to a client SSL certificate (alias for --cert).

--no-interaction
    Do not ask any interactive questions; fail if required input is missing.

-v, --verbose
    Increase output verbosity.

-q, --quiet
    Suppress non‑essential output.

The poetry publish command uploads a built Python package to a remote repository such as PyPI, TestPyPI, or a private index. It works on top of the build command, automatically creating wheels and source archives if the --build flag is supplied. Repository credentials can be stored in ~/.pypirc or supplied on the command line with --username and --password. By default the command targets the repository named pypi, but any repository defined in pyproject.toml can be selected with --repository. Options such as --dry-run let you verify the upload without sending data, while --skip‑existing prevents failures when the same version already exists. The command is commonly used in CI pipelines to automate releases after successful tests and version bumping.

You must have a valid distribution (wheel or sdist) before publishing; otherwise the command fails unless --build is used. Publishing a version that already exists on the target repository will error out unless --skip-existing is supplied. Credentials are read from ~/.pypirc or environment variables; exposing passwords on the command line can be insecure. The command is part of Poetry’s core CLI and requires Poetry 1.0 or newer.

Any repository defined under the [[tool.poetry.source]] table in pyproject.toml can be targeted. Common names are pypi (default) and testpypi. Private indexes (e.g., Artifactory or Nexus) are supported by providing a URL and credentials.

Poetry prefers token‑based authentication (e.g., PyPI API tokens). Tokens can be stored via poetry config pypi-token.pypi or in ~/.pypirc. When using --username/--password, the password may be a token string.

Typical CI steps:
1. poetry install --no-dev
2. poetry version patch (or bump)
3. poetry publish --build --username __token__ --password $PYPI_TOKEN
This ensures reproducible, automated releases without manual intervention.

The poetry publish sub‑command was introduced in Poetry 0.12 (late 2018) as the companion to poetry build. Early versions only supported publishing to PyPI; later releases added the --repository flag, SSL options, and --skip‑existing. With the rise of CI/CD, the command became a staple in automated release pipelines, and Poetry 1.2 added the --dry-run flag to aid safe testing of deployment scripts.

poetry-build(1), poetry-config(1), poetry-add(1), pip(1)