ワークスペースとモノレポ

大きなプロジェクトを (バックエンド、API、共有コードなどの) 小さなパーツに分割することで、整理や管理がより簡単になります。 PyCharm は、このような複数プロジェクトの Python セットアップ（uv ワークスペースやパスベースの依存関係（uv、Poetry、Hatch）を含む）に対応しています。

ワークスペースモードを有効化すると、 pyproject.toml を含むディレクトリが管理対象の Python プロジェクトになります。 PyCharm はワークスペースのメンバーやサブプロジェクトを自動的に検出し、環境を構成し、それらの依存関係を管理します。

ワークスペースモードの有効化

pyproject.toml ファイルを含むプロジェクトを開くと、PyCharm は pyproject.toml ベースのワークスペースが検出されましたというタイトルの通知を表示し、ワークスペースモードの有効化を提案することがあります。

有効化をクリックしてワークスペースモードをオンにしたり、今後表示しないをクリックして通知を閉じたりできます。

ワークスペースモードを有効化すると、PyCharm は pyproject.toml ファイルからワークスペース構造と依存関係を導き出します。

設定でワークスペースモードを有効化

設定ダイアログ (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 でワークスペースメンバーを定義し、それらをワークスペースの依存関係として参照します：

                [tool.uv.workspace]
                members = ["packages/*"]

                [project]
                dependencies = ["my-lib"]

                [tool.uv.sources]
                my-lib = { workspace = true }
            
   

Poetry と Hatch モノレポ

Poetry と Hatch モノレポでは、各プロジェクトは独立して構成され、それぞれに環境があります。

PyCharm はディレクトリ構造内のサブプロジェクトを自動検出し、各プロジェクトに環境を構成します。

自動環境構成

ワークスペースメンバーまたはサブプロジェクトで .py または pyproject.toml ファイルを開くと、PyCharm はこのプロジェクト用の環境がシステム上にすでに存在するかどうかを確認します：

環境が存在する場合は、自動的に SDK として設定されます。
環境が存在しない場合、ファイルレベルの通知で新しい環境の作成とこのプロジェクト用の依存関係インストールを提案します。

提案されるツールは、 pyproject.toml で指定されたビルドツールによって決定されます。ツールが指定されていない場合、PyCharm は uv （システムにインストールされていれば）もしくは venv の使用を提案します。

環境の一貫性

PyCharm は環境の整合性を確認し、 pyproject.toml で定義された依存関係が環境に存在しない場合は警告します。不足している依存関係をインストールするためのクイックフィックスが用意されています。

コードでパッケージをインポートしているが、ワークスペースメンバーの pyproject.toml に記載されていない場合、クイックフィックスでパッケージの環境追加と対応する .toml ファイルの更新を提案します。

プロジェクトの同期

pyproject.toml ファイルを使って pyproject.toml でプロジェクトを同期するアクションでプロジェクトモデルを手動同期できます。この操作で、現在の pyproject.toml ファイルの状態からプロジェクトモデルが再構築されます。

トラブルシューティング

PyCharm はサブプロジェクトの環境構成をシンプルにし、IDE で自動処理できるようにしています。ただし、期待通りに動作しない場合は、バックエンドで実行されたコマンドをトラックし、その出力を Process Output ツールウィンドウで分析できます。

2026 年 7 月 14 日