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

---
title: Poetry Setup and Project Initialization Guide
created: 2026-05-22
tags:
  - python
  - python_tool
  - poetry
  - guide
category: python_tool
status: reference
up: "[[project/index]]"
related:
  - "[[poetry_project_ideas]]"
  - "[[__init__.py explained]]"
source:
author:
published:
---
# 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:
```bash
curl -sSL https://install.python-poetry.org | python3 -
```

### Windows (PowerShell)
Open PowerShell and run:
```powershell
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
```

### Verification
After installation, restart your terminal and verify by running:
```bash
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:
```bash
poetry new my-project
```
This creates a directory named `my-project` with the following structure:
```text
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:
   ```bash
   cd my-existing-project
   ```
2. Run the interactive initialization command mentioned in the introduction:
   ```bash
   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.