ワークスペースとモノレポ
大きなプロジェクトを (バックエンド、API、共有コードなどの) 小さなパーツに分割することで、整理や管理がより簡単になります。 PyCharm は、このような複数プロジェクトの Python セットアップ（uv ワークスペースやパスベースの依存関係（uv、Poetry、Hatch）を含む）に対応しています。
ワークスペースモードを有効化すると、 pyproject.toml を含むディレクトリが管理対象の Python プロジェクトになります。 PyCharm はワークスペースのメンバーやサブプロジェクトを自動的に検出し、環境を構成し、それらの依存関係を管理します。
ワークスペースモードの有効化
Workspace モードはデフォルトで有効になっています。 pyproject.toml ファイルを含むプロジェクトを開くと、PyCharm がそれらのファイルからワークスペースの構造と依存関係を自動的に取得します。
設定で Workspace モードを切り替える
設定 ダイアログ (Ctrl+Alt+S) で、 に進みます。
pyproject.toml ベースのプロジェクトモデルを使用する [ベータ版] チェックボックスをオンまたはオフにします。
ワークスペース構造
プロジェクト検出
pyproject.toml を含むディレクトリは、管理対象の Python プロジェクトとなります。 PyCharm はワークスペース構成を読み込み、すべてのプロジェクトを自動的に検出します。
プロジェクト命名
各プロジェクト名は、 [project] name フィールドが自身の pyproject.toml ファイルに記載されていれば、そこから派生されます。 フィールドがない場合は、ディレクトリ名が代わりに使われます。
IDE 上のプロジェクト名は一意でなければなりません。 複数の pyproject.toml ファイルが同じ名前に解決される場合は、IDE は識別のため @N サフィックス（@1 から開始）を追加します。 これを回避するには、ワークスペース内の各 pyproject.toml に固有の [project] name を記載してください。
依存関係
プロジェクト間の依存関係は、 pyproject.toml 宣言から自動的に解決されます。 依存関係は で閲覧専用として視覚的に表示されます。 変更するには pyproject.toml ファイルを手動で編集してください。
プロジェクト構造は .iml ファイルが .idea ディレクトリ内に保存され、各同期時に pyproject.toml から生成されます。
ワークスペースのセットアップ
使用するツールによって、ワークスペースの構成は以下のように整理できます：
uv ワークスペース
uv ワークスペースは、すべてのプロジェクトで共有される単一の仮想環境を使用します。 ルートの pyproject.toml でワークスペースメンバーを定義し、それらをワークスペースの依存関係として参照します：
Poetry と Hatch モノレポ
Poetry と Hatch モノレポでは、各プロジェクトは独立して構成され、それぞれに環境があります。
PyCharm はディレクトリ構造内のサブプロジェクトを自動検出し、各プロジェクトに環境を構成します。
ルートの pyproject.toml で [tool.poetry] packages テーブルを使用してサブパッケージを宣言している場合、例えば：
自動環境構成
ワークスペースメンバーまたはサブプロジェクトで .py または pyproject.toml ファイルを開くと、PyCharm はこのプロジェクト用の環境がシステム上にすでに存在するかどうかを確認します：
環境が存在する場合は、自動的に SDK として設定されます。
環境が存在しない場合、ファイルレベルの通知で新しい環境の作成とこのプロジェクト用の依存関係インストールを提案します。
提案されるツールは、 pyproject.toml で指定されたビルドツールによって決定されます。 ツールが指定されていない場合、PyCharm は uv （システムにインストールされていれば）もしくは venv の使用を提案します。
環境の一貫性
PyCharm は環境の整合性を確認し、 pyproject.toml で定義された依存関係が環境に存在しない場合は警告します。 不足している依存関係をインストールするためのクイックフィックスが用意されています。
コードでパッケージをインポートしているが、ワークスペースメンバーの pyproject.toml に記載されていない場合、クイックフィックスでパッケージの環境追加と対応する .toml ファイルの更新を提案します。
構成ファイルの依存関係インサイト
PyCharm は pyproject.toml および requirements.txt ファイルで宣言された依存関係についてのインライン情報を提供し、エディターを離れることなくパッケージの詳細を確認できます。
インラインバージョンヒント
pyproject.toml または requirements.txt の各要件定義の横に、PyCharm はパッケージの正確なインストール済みバージョンを灰色のインラインヒントとして表示します。
クイックドキュメント
パッケージの現在のバージョン、ライセンス、上流リポジトリリンクなどの情報を表示するには、パッケージ名にカーソルを合わせるかキャレットを置き、 Ctrl+Q を押してください。
依存関係に移動
Ctrl を押しながらパッケージ名をクリックすると、その仕様をエディタータブで開きます。 内部 Workspace 依存関係の場合、同じ操作でソースモジュールが プロジェクト ツールウィンドウに表示されます。
プロジェクトの同期
pyproject.toml ファイルを使って pyproject.toml でプロジェクトを同期する アクションでプロジェクトモデルを手動同期できます。 この操作で、現在の pyproject.toml ファイルの状態からプロジェクトモデルが再構築されます。
トラブルシューティング
PyCharm はサブプロジェクトの環境構成をシンプルにし、IDE で自動処理できるようにしています。 ただし、期待通りに動作しない場合は、バックエンドで実行されたコマンドをトラックし、その出力を Process Output ツールウィンドウで分析できます。