🫶

pyenv + pipx + poetryでPython環境構築

2024/03/24に公開

Python 3

本記事では、pyenv + pipx + poetryを使ってpython環境を作ります（M1 Macで動作確認しました）。

なぜローカルPCに直接環境を作るのはイマイチなのか？

PCのPythonをそのまま使って開発すると、そのうち以下のような面倒くささが出てきます↓

競合しちゃう

複数のPythonプロジェクトを同時に進める場合、それぞれが必要とするPythonのバージョンや依存ライブラリが異なる可能性があります。ローカルPCに単一のPython環境しか用意していない場合、プロジェクト間での競合が発生する可能性があります。
Pythonは簡単な自動化ツールや分析コードなど、かなりアドホックに色々作成されることが多いです。そのため他の言語よりも複数プロジェクトを切り替えるシーンが多そうに思います。

環境を汚染しちゃう

ローカルPCに直接パッケージをインストールし続けると、いつのまにか不要なパッケージが蓄積し、環境が汚染されてしまう可能性があります。これは依存関係の解決を複雑にし、トラブルシューティングを困難にする原因となります。
新しいプロジェクトを始める際は、クリーンな環境から始めることほうが望ましいです。しかしローカルPCに直接環境を構築すると、前のプロジェクトの影響が残ってしまう可能性があります。

これらの課題を解決するために、Pythonの仮想環境を使うことが推奨されています。仮想環境を使うことで、プロジェクト間で分離された環境を構築できます。

手順概要

1.pyenvのインストール

pyenvは、複数のPythonバージョンを簡単にインストールし、管理できるツールです。

MacでHomebrewを使う場合は以下のコマンドでインストールできます↓

brew update
brew install pyenv

インストール後、以下のコマンドでバージョンを確認できます↓

pyenv -v

使い方：今入っているPythonのバージョンを確認するコマンド

pyenv versions

最初は以下のような出力になるかと思います↓

% pyenv versions

* system (set by /Users/tgc/.pyenv/version)

使い方：インストールできるPythonのバージョンを確認するコマンド

pyenv install --list

インストール可能なPythonのバージョンが出力されます。大量に出力されます。

使い方：Pythonをインストールするコマンド

pyenv install 3.12.2

↑インストールするためちょっと実行に時間がかかります。
インストール後、pyenv versionsでバージョンを確認すると、新しく3.12.2が追加されています↓

% pyenv versions

* system (set by /Users/tgc/.pyenv/version)
  3.12.2

使い方：Pythonのバージョンを切り替えるコマンド

ローカルだけ切り替える（推奨です）

pyenv local 3.12.2

グローバルに切り替える

pyenv global 3.12.2

切り替えコマンド実行後、pyenv versionsでバージョンを確認すると、新しく3.12.2が追加されています↓

% pyenv versions

* system (set by /Users/tgc/.pyenv/version)
  3.12.2

2.pipxのインストール

pipxは、Pythonの実行ファイル(コマンドラインツール)を、システムの他のPythonパッケージから分離して管理するためのツールです。

pipx is a tool to help you install and run end-user applications written in Python. It's roughly similar to macOS's brew, JavaScript's npx, and Linux's apt.
https://github.com/pypa/pipx?tab=readme-ov-file#overview-what-is-pipx より

とあるように、Python版のbrewやnpx、aptです。
brewやaptと似た使い方ならpipx install、npxと似た使い方ならpipx runで実現できます。
今回は、この後のpoetryのインストールの際にpipx install使用します。

brew install pipx
pipx ensurepath

3.poetryのインストール

poetryは、Python向けのパッケージ管理ツール兼依存関係管理ツールです。

先ほどインストールしたpipxを使って、以下のコマンドでインストールします↓

pipx install poetry

↑コマンドの後、ターミナルを再起動する必要があります

また、仮想環境（.venv）をそのディレクトリ内に作成するオプションがあります。複数のPython環境を独立させるためにもオススメです↓

poetry config virtualenvs.in-project true

4.hello world を出力してみる

「普段、グローバルのPythonに色々インストールし、python main.pyと実行している」方を対象にした、pyenv + poetry環境でhello worldを出力する手順サンプルです。もっと手軽な手順はありますが、以下の手順がイメージしやすいかと思います。

4-1.適当なディレクトリを作成する

（割愛）

4-2.pyenvで使いたいバージョンのPythonをインストールする

ここでは、Python3.12.2をインストールします。

pyenv install 3.12.2

4-3.pyenvでバージョンを切り替える

まずは、先ほど作成した適当なディレクトリに移動します。
pyenvでは、〈ローカル（そのディレクトリ内）だけPythonのバージョンを切り替える方法〉と〈グローバルに切り替える方法〉がありますが、ここではローカルのPythonだけ切り替えます。

pyenv local 3.12.2

切り替えが終わると、そのディレクトリに.python-versionファイルが作成されます。.python-versionファイルの中身は、3.12.2という1行だけです↓

% pyenv local 3.12.2

% ls -la
total 8
drwxr-xr-x  3 tgc  staff   96 Mar 24 05:52 .
drwxr-xr-x  4 tgc  staff  128 Mar 24 05:17 ..
-rw-r--r--  1 tgc  staff    7 Mar 24 05:52 .python-version

% cat .python-version 
3.12.2

4-4.poetryで環境設定ファイルを作成する

ディレクトリ直下で、poetry initコマンドを実行します。対話形式で環境構築が始まります。
今回は、最初はそのままEnter連打、yes/noで聞かれた際はno（またはn）で回答、最後はyes（またはy）で回答すればOKです↓

% poetry init

This command will guide you through creating your pyproject.toml config.

Package name [tgc-sample]:  
Version [0.1.0]:  
Description []:  
Author [TGC, n to skip]:  
License []:  
Compatible Python versions [^3.12]:  

Would you like to define your main dependencies interactively? (yes/no) [yes] n
Would you like to define your development dependencies interactively? (yes/no) [yes] n
Generated file

[tool.poetry]
name = "tgc-sample"
version = "0.1.0"
description = ""
authors = ["TGC"]
readme = "README.md"

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


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"


Do you confirm generation? (yes/no) [yes] y

↑の実行後、ディレクトリにpyproject.tomlが作成されているはずです↓

% ls -la
total 16
drwxr-xr-x  4 tgc  staff  128 Mar 24 05:57 .
drwxr-xr-x  4 tgc  staff  128 Mar 24 05:17 ..
-rw-r--r--  1 tgc  staff    7 Mar 24 05:52 .python-version
-rw-r--r--  1 tgc  staff  264 Mar 24 05:57 pyproject.toml

この後の手順を分かりやすくするため、ちょっとpyproject.tomlに追記します↓

pyproject.toml

  [tool.poetry]
  name = "tgc-sample"
  version = "0.1.0"
  description = ""
  authors = ["TGC"]
  readme = "README.md"
+ package-mode = false
 
  [tool.poetry.dependencies]
  python = "^3.12"
 
 
  [build-system]
  requires = ["poetry-core"]
  build-backend = "poetry.core.masonry.api"

4-5.poetryで環境を作成する

poetry installコマンドを実行し、環境を作成します↓

% poetry install
Creating virtualenv tgc-sample in /Users/tgc/Documents/temp/tgc-sample/.venv
Updating dependencies
Resolving dependencies... (0.1s)

Writing lock file

↑の実行後、ディレクトリに.venvやpoetry.lockが作成されているはずです↓

% ls -la
total 24
drwxr-xr-x  6 tgc  staff  192 Mar 24 06:22 .
drwxr-xr-x  4 tgc  staff  128 Mar 24 05:17 ..
-rw-r--r--  1 tgc  staff    7 Mar 24 05:52 .python-version
drwxr-xr-x@ 6 tgc  staff  192 Mar 24 06:22 .venv
-rw-r--r--  1 tgc  staff  245 Mar 24 06:22 poetry.lock
-rw-r--r--  1 tgc  staff  285 Mar 24 06:15 pyproject.toml

4-6.hello worldを出力するコードを書く

main.pyを作成します↓

main.py

print('hello world')

この時点で、こんな感じのディレクトリ構成になってるはずです↓

% ls -la
total 32
drwxr-xr-x  7 tgc  staff  224 Mar 24 06:31 .
drwxr-xr-x  4 tgc  staff  128 Mar 24 05:17 ..
-rw-r--r--  1 tgc  staff    7 Mar 24 05:52 .python-version
drwxr-xr-x@ 6 tgc  staff  192 Mar 24 06:31 .venv
-rw-r--r--  1 tgc  staff   20 Mar 24 06:31 main.py
-rw-r--r--  1 tgc  staff  245 Mar 24 06:30 poetry.lock
-rw-r--r--  1 tgc  staff  285 Mar 24 06:30 pyproject.toml

4-7.実行する

以下のコマンドで、main.pyを実行します↓

% poetry run python main.py 
hello world

↑上手く実行できれば成功です