framework_note/note/python/python tool/poetry_guide.md

title, created, tags, category, status, up, related, source, author, published

title	created	tags	category	status	up	related	source	author	published
Poetry Setup and Project Initialization Guide	2026-05-22	python python_tool poetry guide	python_tool	reference	project/index	poetry_project_ideas __init__.py explained

Poetry Setup and Project Initialization Guide

This guide explains how to install Poetry and start a new Python project, based on the concepts from "Introduction to Poetry - Python Dependency Management".

1. How to Install Poetry

While the introductory notes focus on usage, the standard way to install Poetry is via the official installer script.

macOS / Linux / WSL

Open your terminal and run:

curl -sSL https://install.python-poetry.org | python3 -

Windows (PowerShell)

Open PowerShell and run:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Verification

After installation, restart your terminal and verify by running:

poetry --version

---

2. How to Start a Project

There are two main ways to start a project with Poetry:

Method A: Creating a New Project (Recommended for new folders)

To create a new project with a predefined folder structure:

poetry new my-project

This creates a directory named my-project with the following structure:

my-project/
├── pyproject.toml
├── README.md
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py

Method B: Initializing an Existing Project

If you already have a project folder and want to add Poetry to it:

1. Navigate to your project directory:

   cd my-existing-project
   

2. Run the interactive initialization command mentioned in the introduction:

   poetry init
   

   This will walk you through creating your pyproject.toml file interactively.

---

3. Key Concepts from the Introduction

• pyproject.toml: The single source of truth for your project configuration (replaces requirements.txt, setup.py, etc.).
• Deterministic Resolution: Poetry ensures your dependencies are resolved correctly using a lockfile (poetry.lock).
• Isolation: Poetry automatically manages virtual environments for you, ensuring your global Python installation stays clean.

4. Basic Workflow Commands

Once your project is started, use these commands to manage it:

• poetry add <package>: Add and install a new dependency.
• poetry install: Install all dependencies defined in pyproject.toml.
• poetry shell: Activate the project's virtual environment.
• poetry run <command>: Run a command inside the virtual environment without activating it.