poetry-new

Create a new project (defaults to src layout)

$ poetry new [path/to/directory]

$ poetry new [path/to/directory] [[-i|--interactive]]

$ poetry new [path/to/directory] --name [package_name]

$ poetry new [path/to/directory] --flat

$ poetry new [path/to/directory] --author "[Name <email@example.com>]"

$ poetry new [path/to/directory] --readme [md|rst|txt|...]

poetry new [OPTIONS] PROJECT_NAME
Creates a new Poetry‑managed project with the given name.

PROJECT_NAME
    Name of the project directory to create (also used as the default package name).

--src
    Use the src layout – place the package inside a src/ folder instead of the top‑level directory.

--name
    Explicitly set the package name inside pyproject.toml (useful when the directory name differs).

--description
    Provide a short description for the project; written to the description field.

--author
    Set the author string (e.g., "John Doe ") in the metadata.

--license
    Specify the license identifier (e.g., MIT, Apache-2.0).

--readme
    Choose the README format (markdown, rst, or none).

The poetry new command bootstraps a fresh Python project using Poetry’s standard layout. It creates a directory named after the project and populates it with a minimal but complete structure: a pyproject.toml file for metadata and dependency declaration, a README, a package module (or a src layout if requested), and a basic test suite. The generated pyproject.toml already contains fields for name, version, description, authors, license and the build system, so developers can start coding immediately without worrying about initial configuration. The command is part of the Poetry toolchain, which aims to simplify dependency management, packaging, and publishing for Python projects. It works on any platform where Poetry can be installed (Linux, macOS, Windows/WSL) and requires no additional system packages beyond a working Python interpreter.

The command only creates a skeleton – it does not install any dependencies or create a virtual environment. It requires Poetry to be installed and available in the PATH. Options are limited to those listed; more advanced project scaffolding must be done manually or with custom templates.

Running poetry new my_project yields:
my_project/
├── pyproject.toml
├── README.md
├── my_project/
│ └── __init__.py
└── tests/
└── __init__.py

Poetry was introduced in 2018 by Sébastien Eustace to provide a deterministic, lock‑file‑based workflow for Python packaging. The new sub‑command appeared early in the project to give users a quick way to start a properly configured package. Over successive releases (1.0 in 2020, 1.5‑1.7 in 2023‑2024) the command gained additional options such as --src and richer metadata flags, reflecting community demand for flexible project layouts and better defaults.

poetry init(1), poetry add(1), poetry install(1), poetry build(1)