概要
uvパッケージマネージャでPythonプロジェクトを構成し、PyCharmで開発環境を設定する方法を整理する。
手順
1. pip vs pip3
macOSでは複数のPythonバージョンが共存できる。pipはシステムによってPython 2または3に紐づくが、pip3は常にPython 3に紐づく。最も明確な方法はpython3 -m pip install パッケージ名で実行することだ。どのPythonインタプリタにインストールするか曖昧さがなくなる。
uvを使えばpipを直接使う場面はほとんどない。
2. uvパッケージマネージャ
uvはRustで書かれたPythonパッケージマネージャだ。pipより高速で、プロジェクトごとの仮想環境を自動管理する。
2.1. インストール
brew install uv
2.2. 主要コマンド
uv init # カレントディレクトリでプロジェクト初期化
uv init myproject # myprojectフォルダを作成して初期化
uv add ollama # パッケージインストール + pyproject.tomlに依存関係追加
uv run main.py # 仮想環境でスクリプト実行
uv sync # 依存関係の同期
2.3. Pythonバージョン管理
uv python install 3.13 # Python 3.13をインストール
uv python uninstall 3.14 # Python 3.14をアンインストール
uv python pin 3.13 # プロジェクトのPythonバージョンを固定
uv python list --only-installed # インストール済みバージョンを確認
XcodeにバンドルされたPython 3.9の代わりに最新バージョンをインストールして使うのが良い。Python 3.14はまだ一部のパッケージ（orjsonなど）がサポートしていないため、現時点では3.13が安定的だ。
2.4. 仮想環境
uv initを実行するとプロジェクトルートに.venvディレクトリが作成される。uv runがこの仮想環境を自動的にアクティベートするため、source .venv/bin/activateやdeactivateのようなコマンドを直接使う必要がない。
3. PyCharmインタプリタ設定
PyCharmでuvプロジェクトを実行するには.venvのPythonインタプリタを設定する必要がある。
- 設定 (⌘ + ,) → プロジェクト → Pythonインタプリタ
- インタプリタの追加 → ローカルインタプリタの追加
- 既存 → パスをプロジェクトの
.venv/bin/python3に指定
システムPython（/usr/bin/python3）を使うとuvでインストールしたパッケージを認識できない。
4. macOSローカルネットワーク権限
PyCharmから同じネットワーク上の他のデバイスにアクセスするにはmacOSのローカルネットワーク権限が必要だ。ターミナルでは正常に動作するのにPyCharmだけNo route to hostやConnectionErrorが発生する場合はこの設定を確認する。
システム設定 → プライバシーとセキュリティ → ローカルネットワークでPyCharmを許可すれば良い。
5. PyCharmで韓国語入力時のUnicodeEncodeError
PyCharmのコンソールで韓国語を入力すると、以下のようなエラーが発生することがある。
UnicodeEncodeError: 'utf-8' codec can't encode character '\udce3' in position 151: surrogates not allowed
\udce3はUTF-8 3バイトシーケンス（0xe3）のsurrogate形式だ。PyCharmコンソールのエンコーディング設定の問題で韓国語入力がsurrogate文字に誤って変換され、APIに送信する際にUTF-8エンコーディングが失敗するのだ。
5.1. 解決方法
ヘルプ → カスタムVMオプションの編集…を開き、以下の2行を追加してからPyCharmを再起動する。
-Dfile.encoding=UTF-8
-Dconsole.encoding=UTF-8
設定 → エディタ → ファイルエンコーディングですべての項目がUTF-8になっているかも確認する。
5.2. 確認方法
ターミナルで直接実行してPyCharmの問題かどうか確認できる。
uv run python main.py
ターミナルで正常に動作すれば、PyCharmコンソールのエンコーディング問題だ。
コメントする