VSCodeでpoetryを使ってPython開発を効率的に進めよう！導入手順と解説


## はじめに
Pythonで開発を始めるとき、依存関係の管理や仮想環境の設定ってちょっと面倒ですよね。そんなときに役立つのが「poetry」というツールです。...という内容がpoetryを調べると出てくる内容ですがイメージが湧かなかったので、自分なりにどういった場面でpoetryが活躍するのかの説明と、最低限の導入までの手順をまとめてみました。

## poetryってなに？
poetryは、Pythonのプロジェクト管理をシンプルにしてくれるツールです。

主な特徴は：
- 依存関係を一元管理: pyproject.tomlというファイルで必要なパッケージを管理。
- 仮想環境を自動作成: プロジェクトごとに独立した環境を簡単に作れる。
- 環境の再現性: poetry.lockで依存関係を固定し、他の人と全く同じ環境を共有可能。

次は具体的にこういう場面で使うと便利、という場面を書いてみました。

## poetry使用例
pythonプログラムをローカル環境にて修正、動作確認したい。
その場合に必要な作業として以下があります。
- ①個別にpythonの仮想環境をローカルに構築
- ②動作に必要な外部パッケージやライブラリとそのバージョンを調べてインストール
この２つの作業をすぐに実施できるのがpoetryです。

poetry installコマンドで仮想環境を作成。
その際にpoetry.lockとpyproject.tomlというファイルが配置されていれば、
そのファイルに記載されたバージョンのライブラリやパッケージも一緒に導入されます。

つまりpoetry.lockとpyproject.toml作成してプロジェクトファイルと一緒に配布することで、
メンバーはpoetry installの実行を行うだけでプログラムが動作する環境を作成できます。

pyproject.tomlの中身は以下のようになっています。
```:pyproject.toml
[project]
name = "tamahome2"
version = "0.1.0"
description = ""
authors = [
    {name = "Your Name",email = "you@example.com"}
]
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "requests (>=2.32.3,<3.0.0)"
]

[tool.poetry.dependencies]
python = "^3.7"

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

```
[tool.poetry.dependencies]という部分に依存関係を直接記載、
もしくはコマンドで追加できます。

```
poetry add パッケージ名
```

## ディレクトリ構造
実際にpoetryを使う際は以下のような構造になると思います。

まずは以下のように、プロジェクト配下にpoetry.lockとpyproject.tomlを配置します
```:poetry installの実行前
pj root/
　├ bin/
　├ src/
　│　├ main/
　│　└ conf/
　├ etc/
　├ lib/
　├ poetry.lock
　└ pyproject.toml
```
 後はpoetry installコマンドを実行するだけで仮想環境(./venv)が作成されます。
```:poetry installの実行後
pj root/
　├ .venv/
　├ bin/
　├ src/
　│　├ main/
　│　└ conf/
　├ etc/
　├ lib/
　├ poetry.lock
　└ pyproject.toml
```
それでは実際に導入手順と使い方の例を以下に記載しています。

## VSCodeへpoetry導入
poetryを使うには、まずVSCodeへ導入する必要があります。ここではVSCodeは用意できているけれど、Pythonがまだ入っていない場合も含めて手順を説明します。

### 1. Pythonのインストール（必要なら）
poetryを使うにはPythonが必要です。まだインストールしていない場合、以下を試してください：
- Python公式サイトから最新版（例: Python 3.11）をダウンロード。
- インストーラを実行し、「Add Python to PATH」にチェックを入れて「Install Now」をクリック。
- インストール後、ターミナルで確認：
```:powershell   
python --version
```

「Python 3.x.x」と表示されればOKです。
表示されない場合は、VSCodeの再起動かPowerShellの強制終了から再起動で表示されるはずです。
上記で表示されない場合は、「Add Python to PATH」にチェックを入れずにインストールしている可能性があるので、パスの追加が必要です。

### 2. poetryのインストール
Pythonが入ったら、poetryをインストールします。VSCodeのターミナル（Ctrl+＠で開く）で以下のコマンドを実行：   
- **Windows (PowerShell)**:   
```:powershell   
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -   
```    
   
インストール後、以下で確認：   
```:powershell   
poetry --version   
```   
バージョン（例: poetry version 1.8.2）が表示されれば成功です。もし「コマンドが見つからない」と出たら、後述の「よくあるエラーと対処法」をチェックしてください。   
   
### 3. VSCodeの準備   
VSCodeでpoetryを快適に使うため、Python拡張機能を入れましょう：   
1. VSCodeを開き、左の「拡張機能」アイコン（四角が4つ）をクリック。   
2. 検索バーに「Python」と入力し、Microsoftの「Python」拡張機能をインストール。   
   
これで準備完了です！   
   
## VSCodeでpoetryの仮想環境を起動   
poetryを入れたら、プロジェクトで仮想環境を作って動かしてみましょう。   
   
### 1. 新しいプロジェクトを作成   
適当なフォルダでターミナルを開き、以下を入力：   
```:powershell   
poetry init   
```   
対話形式で質問が始まります。プロジェクト名や依存関係を聞かれますが、とりあえずEnterを押して進めてもOK。Enterで進まない箇所はnでスキップできます。終わるとpyproject.tomlができます。   
   
### 2. 仮想環境を作成・起動   
以下のコマンドを実行：   
```:powershell   
poetry config virtualenvs.in-project true   
```   
poetryは仮想環境をプロジェクトのルートディレクトリ直下の.venvというディレクトリに生成するようになります。   

次に、以下のコマンドを実行：   
```:powershell   
poetry install --no-root   
```   
依存関係がインストールされ、プロジェクトフォルダ内に.venvという仮想環境が作られます。次に、その環境を起動：   
```:powershell   
poetry shell   
```   
ターミナルに(プロジェクト名)-xxxxと表示されれば、仮想環境が動いています。   
poetry shellコマンドが使用できなかった場合は、以下を実行：
```:powershell
poetry self add poetry-plugin-shell
```
これでpoetry shellコマンドが追加されます。


スクリプトが実行できないエラーが出た場合は、WindowsでPowerShellを管理者権限で実行し、以下を実行：
```:powershell   
Set-ExecutionPolicy RemoteSigned
```
コマンドを実行、Yを入力後Enterを押してください。その後VSCodeを再起動してください。   
   
### 3. VSCodeで仮想環境を使う   
VSCodeに仮想環境を認識させましょう：   
1. Ctrl+Shift+P（MacならCmd+Shift+P）でコマンドパレットを開く。   
2. 「Python: Select Interpreter」を選択。   
3. .venv内のPythonパス（例: ./.venv/Scripts/python.exe）を選ぶ。   
これでVSCodeがpoetryの仮想環境を使うようになりました。 
   
## poetry lockで環境構築   
依存関係を追加したいとき、たとえばrequestsパッケージを使いたい場合は：   
```:powershell      
poetry add requests   
```   
これでpyproject.tomlに追加され、仮想環境にインストールされます。   
   
次に、環境を固定するために：   
```:powershell     
poetry lock   
```   
poetry.lockファイルが更新され、依存関係のバージョンが確定します。別のPCで同じ環境を再現したいときは、フォルダをコピーして以下を実行：   
```:powershell     
poetry install   
```   
これだけで同じ環境が作れるはずです。
   
## よくあるエラーと対処法   
初心者がつまずきやすいポイントと解決法をまとめました。   
   
### エラー1: python --versionで「python」とだけ表示   
**原因**: Pythonが正しく認識されていない（Windowsストア版の干渉など）。   
**対処法**: Pythonを公式サイトから再インストールし、「Add Python to PATH」にチェックを入れてください。その後、python --versionで確認。      
   
### エラー2: 仮想環境がVSCodeで認識されない   
**原因**: インタプリタが選択されていない。   
**対処法**: 「Python: Select Interpreter」で.venv`内のPythonを選んでください。

## おわりに
お疲れさまでした。これでVSCodeとpoetryを使ったPython開発環境が整いました。依存関係の管理が簡単になり、他の人と環境を共有するのも楽々です。最初は慣れないかもしれませんが、本当に便利なのでぜひ試してみて下さい。