portableenv 2.0.5

A tool to create virtual environments using an embedded Python interpreter.

portableenv

portableenv creates virtual environments from an embedded Python runtime that is cached under your user profile. Its goal is deterministic, isolated environments that do not silently drift when system Python changes.

Key behavior

• Uses embedded CPython runtime archives from python.org.
• Tracks runtime identity with implementation + version + abi + platform (for example cpython-3.10.9-cp310-win_amd64).
• Writes runtime metadata for embedded runtimes and environment metadata for created environments.
• Runs a post-create health check (doctor) to detect ABI drift (for example cp310 binaries inside a cp314 env).
• Defaults to --copies for stronger isolation.

Version request heuristic

• If you request a patch version (for example 3.11.5), portableenv tries that exact version first, then other discovered 3.11.x patches.
• If you request a minor version (for example 3.11), portableenv probes available patch versions (3.11.x) and tries them in order.
• If no usable embedded 3.11.x runtime is found, it falls back to the current system Python interpreter.
• You can still force system fallback at any time with --allow-system-fallback.

Installation

pip install portableenv

Usage

Create an environment

python -m portableenv myenv

Pin a specific Python version

python -m portableenv myenv -v 3.10.9

Request a minor line and let portableenv choose a patch

python -m portableenv myenv -v 3.11

Explicit system fallback control

python -m portableenv myenv -v 3.10.9 --allow-system-fallback

Use symlinks instead of copies

python -m portableenv myenv -v 3.10.9 --symlinks

Validate an environment (doctor mode)

python -m portableenv myenv --doctor

If ABI mismatches are found, recreate the environment with a consistent runtime.

Notes

• Existing environments are not modified in place.
• If an embedded runtime setup fails and no fallback route is allowed/applicable, creation fails fast.

Requirements

• Python 3.7 or higher
• virtualenv (installed automatically inside the selected runtime)
• Internet connection for first-time runtime and pip bootstrap downloads

License

MIT License. See LICENSE.

Links

• GitHub Repository
• PyPI Package