/commands/poetry/poetry-new-project
poetry new: create a new Python project with Poetry (and poetry init)
- tool
- Poetry
- versions
- Poetry 2.x
- os
- any
poetry new demo-app creates a folder demo-app with a ready pyproject.toml, a package in the src layout (src/demo_app/__init__.py), a tests package and a README.md. In Poetry 2 the file uses the standard [project] table; Poetry-specific settings stay under [tool.poetry]. For an existing folder, poetry init writes only the pyproject.toml.
Create a project
uvx -q poetry@2.5.1 new -q demo-app
find demo-app -type f | sort
echo "--- pyproject.toml"
sed '/^authors = \[/,/^\]/d; /^requires-python/d' demo-app/pyproject.tomlOutput
demo-app/README.md
demo-app/pyproject.toml
demo-app/src/demo_app/__init__.py
demo-app/tests/__init__.py
--- pyproject.toml
[project]
name = "demo-app"
version = "0.1.0"
description = ""
readme = "README.md"
dependencies = [
]
[tool.poetry]
packages = [{include = "demo_app", from = "src"}]
[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"The package name is derived from the project name: demo-app becomes the importable demo_app. The output above hides the authors entry (taken from your Git user name and email, or a placeholder) and the requires-python line (set from the Python that runs Poetry). The example starts Poetry through uvx poetry@2.5.1; with Poetry installed the command is poetry new demo-app.
Options
| Command | What it does |
|---|---|
| poetry new demo-app | New folder with src layout, tests and README |
| poetry new --flat demo-app | Package folder at the project root instead of src/ |
| poetry new --name demo demo-app | Folder demo-app, package called demo |
| poetry new --readme rst demo-app | README.rst instead of README.md |
| poetry new --python ">=3.11" demo-app | Set requires-python explicitly |
| poetry new -i demo-app | Ask the same questions as poetry init (--interactive) |
| poetry init | Write pyproject.toml in the current folder, interactively |
| poetry init -n --name demo | Non-interactive init with defaults |
Next steps
cd demo-app
poetry add requests # runtime dependency
poetry add --group dev pytest # development dependency
poetry install # create the environment and install the project
poetry run pytestpoetry install also installs your own package in editable mode, so import demo_app works in tests. If you only use Poetry to manage dependencies of an application that is never built as a package, set package-mode = false under [tool.poetry] so poetry install skips installing the project itself.
Pitfalls
- Name conflicts.
poetry newrefuses to write into a folder that already exists and is not empty; usepoetry initthere. - Package not found on install. If you rename the folder under
src/without updatingpackagesin[tool.poetry],poetry installfails because it cannot find the package to install. - Running outside the project. Commands such as
poetry addlook forpyproject.tomlin the current folder and its parents; from elsewhere they fail with Poetry could not find a pyproject.toml file. - Poetry 1.x projects have
[tool.poetry.dependencies]instead of[project]. Poetry 2 still reads them, but new projects use the standard format.
How to confirm it worked
poetry check validates the new pyproject.toml and prints All set!. After poetry install, poetry run python -c "import demo_app" exits without error, and poetry env info --path shows where the environment was created.
FAQ
What is the difference between poetry new and poetry init?
poetry new creates a new folder with pyproject.toml, a package folder, tests and a README. poetry init only writes pyproject.toml in the current folder, asking questions interactively, which suits an existing codebase.
Can I use the old flat layout instead of src?
Yes. poetry new --flat demo puts the package folder at the project root. Poetry 1.x used the flat layout by default and needed --src for the src layout.
Where does the virtual environment go?
poetry new does not create one. The first poetry install, poetry add or poetry run creates it, by default in Poetry's cache folder; set virtualenvs.in-project true to get a .venv folder inside the project.