poetry-init

Create a pyproject.toml file interactively

$ poetry init

$ poetry init --name [package_name] --author "[author_name <email@example.com>]"

$ poetry init [[-n|--no-interaction]]

$ poetry init --dependency [package_name]

$ poetry init --dev-dependency [package_name]

$ poetry init [[-h|--help]]

poetry init [--dependency ] [--dev-dependency ] [-l | --license ] [-n | --no-interaction] [--directory ] [-h | --help] [-q | --quiet] [-v | -vv | -vvv | --verbose] [-V | --version] [--ansi] [--no-ansi]

--dependency
    Adds a package dependency to the project. Can be specified multiple times. Format: package_name[:version_constraint] (e.g., requests or requests:^2.25).

--dev-dependency
    Adds a development dependency to the project. Can be specified multiple times. Format: package_name[:version_constraint].

-l, --license
    Sets the project's license. Common choices include MIT, Apache-2.0, GPL-3.0.

-n, --no-interaction
    Runs the command non-interactively, using default values for prompts that are not specified by other options.

--directory
    Specifies the directory where the project should be initialized and the pyproject.toml file created. Defaults to the current working directory.

-h, --help
    Displays help for the init command.

-q, --quiet
    Do not output any message, suppressing all command output.

-v | -vv | -vvv, --verbose
    Increases the verbosity of messages. -v for normal output, -vv for more verbose output, -vvv for debug output.

-V, --version
    Displays the Poetry application version.

--ansi
    Forces ANSI output, even if not detected by the terminal.

--no-ansi
    Disables ANSI output.

The poetry-init command is used to set up a new Python project managed by Poetry. When executed, it interactively prompts the user for essential project information such as the package name, version, description, author, and license. Based on this input, it generates a pyproject.toml file in the current directory. This file is the heart of a Poetry project, defining its metadata, dependencies, and build system.

While it can be run interactively, poetry-init also supports a non-interactive mode using the --no-interaction (-n) flag, allowing for automated project setup by providing all necessary details via command-line options. Unlike poetry new, which creates a new project directory and a basic file structure, poetry-init only focuses on creating or updating the pyproject.toml file in an existing directory, making it suitable for converting existing projects to Poetry or initializing a project in a pre-made directory structure.

poetry-init requires Poetry to be installed on your system. It is best used in an empty directory or at the root of an existing Python project that you wish to convert to Poetry management. Unlike poetry new, it does not create any source files or a predefined project structure; it solely focuses on generating the pyproject.toml file.

When run without the --no-interaction flag, poetry-init will guide you through a series of prompts to gather project details. This is ideal for initial setup. For scripting or automated environments, using -n with other options like --dependency and --license allows for fully unattended project initialization.

The information provided during poetry-init (name, version, description, authors, license) populates the [tool.poetry] section of the pyproject.toml. This metadata is crucial for packaging, publishing, and proper project identification.

The poetry-init command has been a fundamental part of the Poetry dependency management tool for Python since its early development stages, which began around 2017. Its core functionality—to create or update the pyproject.toml file—has remained largely consistent, evolving primarily with general improvements and enhancements to the Poetry ecosystem itself, such as better dependency resolution and metadata handling.

poetry new(1), poetry add(1), poetry install(1), pip(1), setuptools(1)