Pythonプロジェクト移設で.venvを運ばない—データと環境を分ける手順

AIエージェントやデータ処理を日常運用へ入れると、機能が動くことと、安全に繰り返せることの間に差があると分かります。今回取り上げるのは、**巨大なプロジェクトを丸ごとコピーすると、再生成できる仮想環境まで運び、移設後の不整合を招く**という課題です。最近の実施記録で確認できた事実を土台に、別環境でも小さく再現できる形へ整理します。

本文では、実際に確認できたこと、そこから導いた設計判断、まだ完了していない改善を分けます。公開用の例はすべて架空値へ置き換え、メールアドレス、認証情報、内部URL、実在する対象IDは掲載しません。評価・市場データに触れる箇所も、目的はソフトウェアとデータ品質の解説であり、特定の投資や売買を勧めるものではありません。

最近の取り組みで確認できたこと

• **確認事項1**：対象プロジェクト約1.1GBの内訳を調べ、データ約696MB、仮想環境約404MB、コードは10MB弱と確認した。根拠記録は2026-08-22, 2026-08-28, 2026-09-06です。

• **確認事項2**：移設候補ではデータとコードを移し、.venvはコピーせず移設先で再生成する方針を整理した。根拠記録は2026-08-22, 2026-08-28, 2026-09-06です。

• **確認事項3**：外付け領域の読み取り障害を踏まえ、移設前後に同じ検査を行う必要性を確認した。根拠記録は2026-08-22, 2026-08-28, 2026-09-06です。

これらは同じ障害の言い換えではありません。入力を選ぶ段階、処理を起動する段階、結果を保存する段階、集計・表示する段階で、それぞれ別の失敗が起こります。記事化にあたっては、後から確認できない成功を補わず、記録と成果物で確認できた範囲だけを完了事項としました。

なぜ単純な対処では足りないのか

フォルダが大きいと、最初に『不要ファイルを削る』発想へ向かいがちです。しかし安全な移設では、消せるかより再生成できるかで分類します。ソース、設定、ロックファイル、業務データ、生成レポート、キャッシュ、仮想環境では保全方法が異なります。

仮想環境は依存パッケージの実体を含むため容量が大きくなりますが、正しい依存定義とロックファイルがあれば再構築できます。一方、状態DBや収集済みデータは再取得できない場合があるため、同じ扱いで除外してはいけません。

短期的な復旧だけなら手動再実行や表示上の調整で終えられる場合があります。しかし日次運用では、翌日も同じ判断を人が繰り返さない仕組みが必要です。そのため、原因の説明だけでなく、入力の固定、上限、証拠、ロールバック、完了条件までを一つの運用契約として定義します。

仕組みを分解する

1. **容量を分類**
2. **再生成物を除外**
3. **データを検証コピー**
4. **環境を再構築**

移設台帳を『必須』『再生成可能』『一時』『要判断』の四区分で作ります。必須にはソース、設定例、依存定義、ロックファイル、移行対象データを入れます。再生成可能には.venv、ビルド成果物、キャッシュを入れ、移設後の再生成コマンドを併記します。

データはファイル数、合計サイズ、重要ファイルのハッシュ、SQLiteなら整合性結果を移設前後で比較します。単にコピーコマンドが0で終わっただけでは、読み取り不能ファイルや途中変更を見逃すためです。稼働中DBはバックアップAPI等で一貫したスナップショットを作ります。

各段階には機械が判定できる終了条件を置きます。「たぶん正常」「画面が開いた」ではなく、どの入力に対して何を検査し、どの成果物が残ったら次へ進むかを記録します。段階を跨ぐデータにはrun IDと基準時刻を付け、別日の結果が混ざらないようにします。

小さく再現する手順

本番環境を直接変更せず、`/path/to/project`配下の架空データで試します。認証値は`YOUR_TOKEN`のようなプレースホルダーを使い、実値を履歴や画面キャプチャへ残さないでください。

1. **架空プロジェクトでsrc・data・.venv・cacheの容量を別々に集計する**
2. **pyproject.toml、uv.lock、Python版指定、外部サービス設定の有無を確認する**
3. **.venvとキャッシュを除外した移設計画を作り、元データは削除せずコピーする**
4. **移設先でuv sync –lockedを実行し、ロック不整合なら勝手に更新せず停止する**
5. **単体テスト、起動確認、読み取り専用データ検査を通してから切り替える**

“`text
project/
src/ # move
data/ # move and verify
pyproject.toml # move
uv.lock # move
.venv/ # rebuild
.cache/ # rebuild or discard
“`

最初の実験では対象を3〜10件に絞ります。正常系だけでなく、入力欠損、途中停止、二重実行、保存後の検証失敗を意図的に作ります。失敗fixtureを用意すると、単に例外が出るかではなく、安全に止まり、理由が通知され、次回再開に必要な状態が残るかまで確認できます。

再実行は同じ操作の繰り返しに見えても、新しい費用・状態更新・外部通信を発生させます。したがって、元の状態を読み取り専用で保存し、変更対象を列挙し、上限を確認してから実行します。成功後も、予定した対象と保存された対象をID単位で照合します。

確認指標

• 移設前後の必須ファイル数
• データハッシュ不一致数
• 再構築時間
• 移設後テスト成功率

まずコピー元を残したまま移設先を構築します。依存同期は`–locked`を使い、ロックファイルが古ければ明示的に失敗させます。この段階で依存更新まで同時に行うと、移設障害とバージョン差の原因を分離できません。

起動確認では画面が開くことだけでなく、代表データの読み込み、DBの読み取り、定例スクリプトのdry-runを確認します。切り替え後も一定期間は元環境を読み取り専用で保持し、問題があれば戻せるようにします。

指標には母集団、基準日、計測時刻、取得元を添えます。閾値はこの記事の観測値をそのまま流用せず、自分の処理件数、許容時間、業務影響から決めます。暫定値は暫定、推定値は推定、取得不能は取得不能として扱い、0へ変換しません。

日常運用へ入れるルール

• 容量調査結果を移設台帳に残す
• 再生成コマンドをREADMEへ固定する
• 元環境の削除日は移設成功とは別に判断する

通知は成功・警告・失敗を分けます。成功通知にも、処理件数、検証済み件数、基準日、成果物への参照を含めます。警告は自動継続したのか、人の判断を待って停止したのかを明記します。詳細ログをそのまま送るのではなく、秘密情報を除いた要約とrun IDを渡します。

また、設定変更と本処理を同時に行わないことも重要です。復旧のために依存更新、データ移設、再実行を一度に行うと、成功しても何が効いたか分かりません。一つずつ変更し、同じ検査を繰り返せる形にします。

失敗しやすい点と安全策

1. .venvを時間短縮のためコピーする

ロックファイルから移設先で再生成する。さらに、変更前後の証拠を同じ形式で残し、成功表示だけで判断しません。

2. dataを生成物として一括除外する

再取得可能性と正本性で個別分類する。さらに、変更前後の証拠を同じ形式で残し、成功表示だけで判断しません。

3. 依存更新と移設を同時に行う

同一ロックで移設後、更新は別変更にする。さらに、変更前後の証拠を同じ形式で残し、成功表示だけで判断しません。

4. コピー直後に元を削除する

読み取り専用の戻し先を保持期間付きで残す。さらに、変更前後の証拠を同じ形式で残し、成功表示だけで判断しません。

安全策の共通点は、処理の外側に確認可能な証拠を残すことです。対象一覧、設定版、実行時刻、終了理由、成果物件数が別々に残っていれば、モデルの回答が途切れたりUIが変わったりしても状況を復元できます。

再現チェックリスト

• [ ] 根拠にした実施日と確認範囲を記録した
• [ ] 入力・状態・成果物を別々に保存した
• [ ] 正常な0、欠損、エラーを区別した
• [ ] 小さなfixtureで正常系と異常系を試した
• [ ] 再実行時の重複・上限・戻し方を決めた
• [ ] 個人情報、秘密値、内部URLを公開例から除いた
• [ ] 未完了の改善を実装済みとして書いていない

判断記録を残す

実装の最終結果だけでなく、採用しなかった案も短く残します。判断日、選択肢、採用理由、影響範囲、戻し方の五点があれば、次の担当者は同じ調査を繰り返さずに済みます。数値を残す場合は、その数値が観測値、推定値、推奨閾値のどれかを明記します。

今回のような運用改善は、一回の成功だけでは完成と判断できません。翌日の自動実行、失敗時の停止、再実行後の突合まで確認して初めて定着したといえます。ブログでも、実装済み、検証済み、継続観察中、構想段階を混ぜず、読者がどこまで再現してよいか分かる表現にします。

判断記録には、変更前と変更後の小さなサンプルも添えます。ログ全体や実データを転載する必要はありません。入力3件、期待結果、実際の結果、差分理由だけを匿名化して残せば、後日の仕様変更でも同じ観点を再検証できます。サンプルの生成方法と確認コマンドも併記し、画面を見た人だけが分かる知識にしないことが大切です。自動テストで確認した範囲と、人が目視した範囲も分けて書きます。

次に改善するなら

次の改善候補は、**移設台帳と前後検証を自動化し、データ・環境・キャッシュの分類漏れを検出する**ことです。これは2026-09-14時点では次段階であり、完了済みとは扱いません。実装する際は小さなfixtureと明示的な上限から始め、日次処理へ接続した後も数回の実運用を観察します。

参考情報

• 本記事の根拠にした実施記録日: 2026-08-22, 2026-08-28, 2026-09-06
• 情報・公式仕様の確認日: 2026-09-14
• [uv project structure](https://docs.astral.sh/uv/concepts/projects/layout/)
• [uv locking and syncing](https://docs.astral.sh/uv/concepts/projects/sync/)

公式ドキュメントは現在の機能・コマンド・制約を確認するために参照し、ローカルで実施した結果は日次記録と成果物で確認しました。仕様、価格、提供条件は変更される可能性があるため、再現時には掲載リンクをもう一度確認してください。