Python開発環境構築: pyenv + poetry + VS Code

2025年3月29日2025年4月13日

雑記

先日、新しいMacBookProをGETしたので、真っ先に環境構築してみました。メモとしてPython開発環境を構築する方法を残しておきます。pyenvでPythonバージョン管理、poetryでパッケージ管理を行い、VSCodeで快適なコーディング環境を実現することがゴールです。

Pythonを用いた地理空間分析の基本

地理空間データ分析は、位置情報を持つデータを分析し可視化することで、地理学、歴史学、考古学、都市計画、環境モニタリング…

2025年4月3日 2025年4月6日

目次 [ close ]

環境構築の全体像

pyenvとpoetryを組み合わせることで、プロジェクトごとに独立した環境を構築できます。pyenvはPythonのバージョンを管理し、poetryは依存パッケージを管理してくれるため、「動作環境を完全に揃える」という開発の基本が実現できます[6]。

1. Homebrewのインストール

MacでのパッケージマネージャーであるHomebrewをまずインストールします：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

インストール後、以下のようなメッセージが表示されるので、指示通りにPATHを設定します[7]：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

2. pyenvのインストールと設定

Homebrewを使ってpyenvをインストールします：

brew install pyenv

シェル設定ファイルにpyenvの初期化コードを追加します。zshの場合（MacOSのデフォルト）：

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

変更を反映させるためにシェルを再起動するか、以下を実行します：

source ~/.zshrc

3. Pythonのインストール

pyenvを使って必要なPythonバージョンをインストールします：

# 利用可能なバージョンの確認
pyenv install --list

# 特定のバージョンのインストール（例：3.10.2）
pyenv install 3.10.2

# インストールしたバージョンを確認
pyenv versions

# グローバルPythonバージョンの設定
pyenv global 3.10.2

注意: Apple Silicon搭載Macの場合、pyenvでインストールできるのはApple Silicon用のバイナリが提供されているバージョンのみです。一般的に新しめのバージョン（3.8以降）であれば問題ありません[8]。

4. poetryのインストール

公式の方法でpoetryをインストールします：

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

PATHを追加します（インストール後の指示に従ってください）：

export PATH="$HOME/.poetry/bin:$PATH"

.zshrcなどに上記を追加しておくとよいでしょう。

poetryの設定を行います。特に仮想環境をプロジェクトディレクトリ内に作成する設定はVS Codeとの連携に重要です：

poetry config virtualenvs.in-project true

5. VS Codeのインストールと設定

Homebrewを使ってVS Codeをインストールします：

brew install --cask visual-studio-code

VS Codeを起動し、以下の拡張機能をインストールします：

Python（Microsoft）
Pylance
Black Formatter（コードフォーマッター）
isort（importの整理）
Flake8（リンター）
Mypy Type Checker（型チェック）[7]

VS Codeの設定は、.vscode/settings.jsonに以下を追加することで行えます：

{
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  },
  "isort.args": ["--profile", "black"],
  "flake8.args": [
    "--max-line-length=79",
    "--max-complexity=10"
  ],
  "mypy-type-checker.args": [
    "--ignore-missing-imports",
    "--disallow-untyped-defs"
  ]
}

プロジェクトの作成と管理

新規プロジェクトの作成

# プロジェクトディレクトリ作成
mkdir my_project
cd my_project

# プロジェクト固有のPythonバージョンを設定
pyenv local 3.10.2

# poetryでプロジェクトを初期化
poetry init

初期化時には対話形式で必要事項を入力します。完了するとpyproject.tomlファイルが生成されます[9]。

依存パッケージの管理

# 依存パッケージをインストール
poetry install

# パッケージを追加
poetry add <package-name>

# 開発専用パッケージを追加
poetry add <package-name> --dev

# パッケージを削除
poetry remove <package-name>

仮想環境の使用

# 仮想環境内でシェルを起動
poetry shell

# または特定のコマンドを仮想環境内で実行
poetry run python your_script.py

VS Codeでの開発環境設定

Pythonインタープリターの選択

VS Codeでプロジェクトを開く
コマンドパレットを開く（Cmd+Shift+P）
Python: Select Interpreterを選択
.venv/bin/python（poetryで作成した仮想環境）を選択

VS Codeにpoetryの環境を認識させるには以下の手順も効果的です[4]：

poetry env info --pathでパスを取得
VSCodeの設定で「Python: Venv Path」にこのパスを設定

これで、VS Codeのターミナルを開くと自動的に仮想環境が有効化されます[4]。

開発ワークフロー

プロジェクトディレクトリに移動
poetry shellで仮想環境を有効化
VS Codeで開発（コード補完、型チェック、リンティングが自動的に機能）
poetry addで必要なパッケージを追加
poetry run python your_script.pyでスクリプトを実行

結論

pyenv、poetry、VS Codeの組み合わせは、Pythonプロジェクトの依存関係を明確にし、再現性のある開発環境を構築する強力な方法です。この環境では、コードの品質を保ちながら、効率的な開発が可能になります[2][6]。

また、この方法はチーム開発でも特に効果を発揮します。全員が同じ環境で開発できるため、「自分の環境では動くのに」という問題を回避できます[6]。

新しいMacBook Proでのコーディングライフをお楽しみください！

情報源
[1] pyenv and poetry – GitHub Gist https://gist.github.com/tanhaa/f492cda93987d1ffcc7566d0e9142cd9
[2] VSCodeとPoetryで作るPython開発環境 – Zenn https://zenn.dev/alivelimb/articles/20220501-python-env
[3] Setup VS Code for Python with Pyenv and Poetry – YouTube https://www.youtube.com/watch?v=547Jr26duHQ
[4] VSCodeにPoetryの仮想環境を認識させる – Zenn https://zenn.dev/bee2/articles/74b975c70ae6ed
[5] 環境構築(pyenv/poetry) :: Jun Nishii https://bcl.sci.yamaguchi-u.ac.jp/~jun/notebook/python/install-poetry/
[6] チームにおける円滑なPython開発環境 [Poetry + pyenv + black + isort] https://qiita.com/MasashiSD/items/a8ddc0b039a5b112b109
[7] M1 MacBook ProでPythonとVisualStudioCodeの環境設定 – Qiita https://qiita.com/IKEH/items/a23554fee13085352a32
[8] M1 MacのPython環境 ~pyenv + poetry – VOMIT https://vomit.me/articles/2022/12/02/159237bea0dad3399605c516d6b83aa6/python-env-m1/
[9] Python Poetry and VS Code (2024) | John Maeda’s Blog https://maeda.pm/2024/03/03/python-poetry-and-vs-code-2024/
[10] 【Python】環境構築 | AppleSilicon搭載Mac – Zenn https://zenn.dev/kou1924/articles/560cda6c8b795c
[11] 【2024最新版】Python環境構築完全攻略 Mac編 … – YouTube https://www.youtube.com/watch?v=kr-MBPE-QIQ
[12] 仮想環境作ったつもりなのにライブラリが呼び出せない！｜python … https://note.com/fline/n/n5f2af1a37ed1
[13] 【2024最新版】Python環境構築完全攻略 Mac編 – YouTube https://www.youtube.com/live/kr-MBPE-QIQ
[14] 【Python】macOSのPython開発環境の作成〜macOS Sequoia 15.2版 https://note.com/kuromaro0220/n/ne47ff49269d6
[15] 2025年最新版 Python環境構築完全攻略【Mac編】 https://hoshi-it-o.com/python-build-environment/
[16] pyenv+PoetryでのPython環境構築方法を覚えられない人（私 … – Qiita https://qiita.com/Ryku/items/512a6744bfa9903bf2dd
[17] VSCodeのPython環境設定[poetry+ruff,mypy] – Qiita https://qiita.com/tamo_breaker/items/dbd8482e88c61269d531
[18] M1 MacでpyenvとpoetryをインストールしてPython3.10.10環境を構築 https://qiita.com/nokonoko_1203/items/a694be4e76da0872f51a
[19] pyenv and poetry installation on MacOSX – Stack Overflow https://stackoverflow.com/questions/68046245/pyenv-and-poetry-installation-on-macosx
[20] Python(pyenv+poetry)環境構築 for Mac – Optigressor https://optigressor.com/dev/python-pyenv-poetry-for-mac/
[21] pyenv + pipx + poetryでPython環境構築 – Zenn https://zenn.dev/tgc/articles/fc88b3c8c47e48
[22] pyenv+poetryで Python 仮想環境を作る – deepblue https://blog.deepblue-ts.co.jp/virtual_env/pyenv_poetry/
[23] 2022年度版Python環境構築徹底解説 – Qiita https://qiita.com/kjm_nuco/items/733d67ff39acb41839f2

Which sites in Japan will be inscribed on the World Heritage List in the future?

めざせ世界遺産！彦根城の最新情報2025年3月

Minecraftで甦る日本の名城：姫路城など歴史的建造物の再現テクニック