pyenv/plugins/pyenv-binary/README.md

# pyenv-binary (experimental)

Package an installed Python version into a relocatable archive that can be
installed on another machine.

This is experimental and intentionally decoupled: it does not change
`pyenv install` or any other command. You drive it explicitly through
`pyenv binary`. Run `pyenv binary <command> --help` for details on a command.

## Portability

An archive is portable across machines that share its build platform (OS,
architecture and a compatible libc) and have the recorded system libraries. It
is not portable across, say, glibc and musl, or to an older glibc; the platform
and dependency metadata exist to catch that.

## Commands

### `pyenv binary save <version> [<output-dir>]`

Packs an installed version into `<version>-<platform>.tar.gz` (relative paths)
and writes `<version>-<platform>.meta` describing the build platform (OS, arch,
distro and libc version) and the system libraries the build links against.

```sh
pyenv binary save 3.12.7 ./dist
```
Add an experimental pyenv-binary plugin with a save command (#3487) * pyenv-binary: add experimental plugin skeleton Adds a new plugin, decoupled from `pyenv install`, for packaging and installing relocatable Python binaries. This commit is just the command dispatcher; the individual subcommands follow. `pyenv binary <command>` dispatches to the matching script under the plugin's libexec, so subcommands stay out of the top-level `pyenv commands` list. Groundwork for the binary distribution support discussed in #2334. * pyenv-binary: add the `save` subcommand `pyenv binary save <version> [<output-dir>]` packs an installed version into a relocatable .tar.gz with relative paths and writes a metadata file recording the build platform, distro, libc version and the external system libraries the build links against (via `ldd` on Linux, `otool -L` on macOS). * pyenv-binary: reject invalid version names and drop readlink -f in save A version is a single directory name under versions/, so refuse names with a slash or a dot-dot component before building the prefix path. Also emit the python paths directly instead of `readlink -f`, which BSD readlink on macOS does not support; ldd/otool follow the symlinks anyway, so the resolved paths were never needed. * pyenv-binary: test the `save` subcommand Cover argument validation, the version-name guard, and packaging an installed version into an archive with matching metadata. * pyenv-binary: test dependency parsing and tighten the version guard Add tests that feed realistic ldd and otool listings through save and check only the libraries resolving outside the prefix end up in the metadata, since that filtering is the fiddliest part of the command. Narrow the version guard to reject `.' and `..' rather than any name containing a dot-dot, now that a slash is already refused, and note why the find still matches .so. even though CPython does not produce them. 2026-07-03 11:38:54 +05:30			`# pyenv-binary (experimental)`

			`Package an installed Python version into a relocatable archive that can be`
			`installed on another machine.`

			`This is experimental and intentionally decoupled: it does not change`
			`pyenv install` or any other command. You drive it explicitly through
			`pyenv binary`. Run `pyenv binary <command> --help` for details on a command.

			`## Portability`

			`An archive is portable across machines that share its build platform (OS,`
			`architecture and a compatible libc) and have the recorded system libraries. It`
			`is not portable across, say, glibc and musl, or to an older glibc; the platform`
			`and dependency metadata exist to catch that.`

			`## Commands`

			### `pyenv binary save <version> [<output-dir>]`

			Packs an installed version into `<version>-<platform>.tar.gz` (relative paths)
			and writes `<version>-<platform>.meta` describing the build platform (OS, arch,
			`distro and libc version) and the system libraries the build links against.`

			```sh
			`pyenv binary save 3.12.7 ./dist`
			```