| name | macos-deploy-python-tool-from-github |
| description | Use when deploying a Python tool from GitHub on macOS Apple Silicon. |
macOS 部署開源 Python 工具(GitHub → 本地運行)
從 GitHub clone 一個 Python 開源項目,喺 macOS Apple Silicon 上完整部署並可使用。
典型流程
1. Clone 項目
git clone https://github.com/username/project.git ProjectName
cd ProjectName
2. 檢查環境
python3 --version
pip3 --version
which git
ffmpeg -version | head -2
3. 安裝依賴
睇 README 推薦方式,通常兩種:
uv sync --frozen
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
4. 設定 config
項目通常有 config.example.toml,複製一份:
cp config.example.toml config.toml
然後按 README 改 key 同 provider。
5. 連接本地 Ollama LLM(如適用)
如果項目支援 Ollama 做 LLM provider:
ollama --version
ollama list
6. 啟動服務
uv run streamlit run ./webui/Main.py --browser.gatherUsageStats=False
或者直接:
cd ProjectName && uv run streamlit run ./webui/Main.py
常見問題 & Fix
⚠️ FFmpeg x265 library missing
Error: dyld: Library not loaded: /opt/homebrew/opt/x265/lib/libx265.215.dylib
原因:Homebrew 更新咗 x265 但 FFmpeg 冇同步更新。
Fix:
brew reinstall ffmpeg
驗證:ffmpeg -version 正常顯示就 OK。
⚠️ .venv path 錯誤(搬遷項目後)
Error: Failed to spawn: streamlit. Caused by: No such file or directory
原因:搬咗項目 folder 但 .venv 入面仲係硬編碼舊 path。
Fix(重建 venv):
cd /new/project/path
rm -rf .venv
uv sync --frozen
⚠️ config.toml 格式錯誤
Error: TomlDecodeError: Found invalid character in key name
原因:用 read_file 寫入時 embedded line number prefix。
Fix:用直接寫入方式,或者從 config.example.toml 重新複製再 patch。
cp config.example.toml config.toml
⚠️ Streamlit 卡喺 Email prompt
頭一次啟動 Streamlit 會問 email,送個空 Enter 就得。
--browser.gatherUsageStats=False
Desktop Shortcut
建立一個 .command 檔案:
cat > ~/Desktop/ProjectName.command << 'EOF'
cd /path/to/ProjectName
uv run streamlit run ./webui/Main.py --browser.gatherUsageStats=False
EOF
chmod +x ~/Desktop/ProjectName.command
雙击就會開 Terminal 啟動。
驗證 checklist