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 = "[e-mail]"}
]
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開発環境が整いました。依存関係の管理が簡単になり、他の人と環境を共有するのも楽々です。最初は慣れないかもしれませんが、本当に便利なのでぜひ試してみて下さい。