Sign in Subscribe

【開發筆記-1】如何從頭安裝 Python 環境與 Poetry 2.0 設定

【開發筆記-1】如何從頭安裝 Python 環境與 Poetry 2.0 設定

2025.02.09 新增總結

最近因為想在家運行 LLM 和開發相關專案，添購了一台 Mac mini M4
於是又重啟了每個開發者必經的「環境安裝」天堂路 🥹
想必每個人的菜鳥時期都有經歷過這一段，深夜在爬各種 Stack Overflow, Github issue…

幸好生成式 AI 的出現，讓這一段天堂路痛苦指數直接打 2 折有吧！

但是還是有蠻多坑可能會遇到的，尤其是有在用 Poetry 的朋友
因為 Poetry 2.0 的更動蠻多，所以趁這個機會順便也記錄一下

💡
注意：本篇以 MacOS M4 的安裝環境為主

▋安裝 Python

首先在 MacOS 中安裝軟體和套件，我們最好有 package 管理工具
package 的依賴 (dependency) 管理真的很重要啊！！！！

  • 尤其 MacOS 的環境如果弄髒了通常處理起來會很麻煩，這裡我推薦新的電腦都先安裝 Homebrew
    官方安裝指令：
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  • 接下來 Python 的安裝推薦使用 Pyenv
    Pyenv是一個開源的Python版本管理工具，旨在幫助開發者輕鬆地安裝和切換多個Python版本。
    這個工具特別適合需要在不同專案中使用不同Python版本的開發者，因為它能夠避免系統默認Python安裝的衝突和問題。
  1. 用 Homebrew 安裝 Pyenv
  2. 安裝特定版本的 Python (例如 3.10.13)
  3. 設定全局 Python 版本
  4. 確認 Python 安裝成功
$ brew install pyenv
$ pyenv install 3.10.13
$ pyenv global 3.10.13
$ python --version

▋安裝與使用 Poetry (2.0.1)

  1. 使用官方推薦的安裝方式：
  2. 確保 Poetry 被添加到您的 PATH 中
    1. 開啟環境設定檔
    2. 加入 PATH
    3. 重新載入配置
  3. 驗證 Poetry 安裝
$ curl -sSL <https://install.python-poetry.org> | python3 -

$ vim ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"
$ source ~/.zshrc

$ poetry --version
  • 接下來我們要做一些重要設定，這便我先快速帶過我常用的設定，詳細的說明另外寫一篇介紹 Poetry 🚩
  1. 設定 Poetry 將虛擬環境建立在專案資料夾中
  2. 在 pyproject.toml 中禁用 package mode (2.0.1 更新)
    詳細內容可以參考官網 2.0.0 release note
$ poetry config virtualenvs.in-project true

# Add to pyproject.toml
[tool.poetry]
package-mode = false
  1. 安裝專案所需要的套件有兩種方式
# 開一個新的 Poetry 專案
$ poetry init
$ poetry add numpy
$ poetry install

# 已經有 Poetry 專案，做安裝
$ poetry lock
$ poetry install --no-root
  1. 啟動虛擬環境在 2.0.1 有一個重要更動，就是棄用 poetry shell 移入 plugin 中(官網說明)
    因為需要手動開起 shell 再執行 poetry env activate，所以我直接設定一個快捷鍵
# 版本 2.0.1 之前
$ poetry shell

# 版本 2.0.1 
$ eval $(poetry env activate)

# 設定快捷鍵
$ vim ~/.zshrc
# Add to .zshrc
alias poetry-in='eval $(poetry env activate)'
# 重新載入設定
$ source ~/.zshrc
# 用快捷鍵啟動虛擬環境
$ poetry-in

▋總結

簡單來說，我們安裝 Pyenv 管理整台電腦的 Python 版本，避免手動安裝多個版本 Python 之後在環境 MacOS 環境發生衝突，接著在每個專案使用 Poetry 創建虛擬環境，管理不同專案所需要用到的套件。
這樣一來，就比較不容易發生升級了新的套件，導致別的專案無法使用的困境。

如果是管理不同服務 (運行中的程式)，就會用到 Docker 將不同服務用容器 (container) 來做管理，那就是另一塊領域了，這裡就不再深入。

希望對新手和需要重建環境的人有幫助！