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

目次 [ close ]
  1. 環境構築の全体像
    1. 1. Homebrewのインストール
    2. 2. pyenvのインストールと設定
    3. 3. Pythonのインストール
    4. 4. poetryのインストール
    5. 5. VS Codeのインストールと設定
  2. プロジェクトの作成と管理
    1. 新規プロジェクトの作成
    2. 依存パッケージの管理
    3. 仮想環境の使用
  3. VS Codeでの開発環境設定
    1. Pythonインタープリターの選択
  4. 開発ワークフロー
  5. 結論

環境構築の全体像

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を起動し、以下の拡張機能をインストールします：

  1. Python（Microsoft）
  2. Pylance
  3. Black Formatter（コードフォーマッター）
  4. isort（importの整理）
  5. Flake8（リンター）
  6. 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インタープリターの選択

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

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

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

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

開発ワークフロー

  1. プロジェクトディレクトリに移動
  2. poetry shellで仮想環境を有効化
  3. VS Codeで開発（コード補完、型チェック、リンティングが自動的に機能）
  4. poetry addで必要なパッケージを追加
  5. 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