Choosing a Python Project and Dependency Workflow

Python's environment and packaging ecosystem offers several valid workflows. Moving from `venv` to Pipenv is not automatically an upgrade: `venv` creates an isolated environment, while workflow tools may additionally resolve dependencies, create locks, build packages, publish artifacts, or run tasks. Start with the capabilities a repository needs. This guide was verified on 2026-08-01 against the [Python Packaging User Guide tool recommendations](https://packaging.python.org/en/latest/guides/tool-recommendations/), the [`venv` documentation](https://docs.python.org/3/library/venv.html), and the [reproducible-environments specifications](https://packaging.python.org/en/latest/specifications/). ## Current mental model Separate four concerns: 1. An interpreter manager, such as pyenv, selects a Python release. 2. An environment manager isolates installed packages. Standard `venv` is the minimal baseline. 3. A resolver selects compatible dependency versions. 4. A build backend creates a wheel or source distribution when the project is packaged. A single tool may cover several concerns, but the project should still document which files are authoritative and which outputs are regenerated. ## A safe minimal baseline ```bash python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -r requirements.txt python -m pip check python -m pytest ``` Use `python -m pip` to make the target interpreter explicit. Keep `.venv/` out of Git. For an application that requires fully repeatable deployments, add the repository's chosen lock or compiled-constraints workflow rather than relying on an old environment's `pip freeze` output. ## Choosing among tools - `venv` plus pip is broadly available and easy to debug, but does not prescribe one lock workflow. - pip-tools compiles reviewed requirement inputs into pinned outputs and fits many existing pip deployments. - Pipenv manages a virtual environment and `Pipfile.lock`; keep it when the team and automation already depend on that contract. - Poetry and PDM provide project metadata, resolution, locking, and packaging workflows with different conventions. - Hatch focuses on project environments, builds, publishing, and task-like scripts. - uv provides fast environment and dependency workflows and supports several modern Python packaging standards. Tool popularity is not a migration requirement. Evaluate supported Python versions, platform behavior, private index authentication, lock portability, CI installation, editor support, and maintainer continuity. ## Migration without deleting evidence 1. Record the current interpreter, direct dependency declarations, lock or constraints files, and successful test commands. 2. Create a new branch and a separate clean environment. Do not delete the working environment yet. 3. Configure the candidate tool from direct project intent, not by declaring every transitive package as direct. 4. Resolve and inspect changes in versions, hashes, indexes, and platform markers. 5. Run unit, integration, build, and smoke tests on every supported platform. 6. Update CI and onboarding documentation in the same change. 7. Prove a clean clone can reproduce the workflow before removing the old files. Never make `rm -rf venv` the first migration step. An environment is disposable only after its requirements and working verification commands are preserved. ## Application versus library tradeoffs Applications often lock the complete deployable environment. Libraries generally declare compatible dependency ranges so downstream applications can resolve them. Test a library against its supported range rather than publishing an application-style lock as a consumer requirement. For standalone Python commands, use `pipx` to isolate the installed application. For CI publishing to PyPI, prefer trusted publishing where supported rather than a long-lived upload token. ## Verification gate ```bash python -c 'import sys; print(sys.executable, sys.version)' python -m pip check python -m build python -m pytest ``` Use only commands relevant to the repository, but require a clean-clone installation and the same production entry point used before migration. Keep the old workflow available until the new path passes those gates and the rollback is understood. ## Operational checks after migration A resolver change can affect installation time, cache behavior, artifact size, private-index requests, and failure messages in CI. Confirm that dependency automation can still update the authoritative declaration and that developers do not need personal credentials in committed configuration. Test an unavailable index so bootstrap fails clearly instead of using an unexplained global package. Document how to add, remove, and update a direct dependency; how to regenerate resolved output; and which files reviewers inspect. Include the supported Python matrix and the command that proves the active interpreter. A future teammate should reproduce the environment from a clean checkout without knowing which tool was popular when the repository was created.

1
2
3
4
5
6

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip check
python -m pytest

1
2
3
4

python -c 'import sys; print(sys.executable, sys.version)'
python -m pip check
python -m build
python -m pytest