Portable python binaries
Portable-Python is a CLI (and a python library) for compiling python binaries from source than can be decompressed in any folder, and used from there without further ado (ie: no need to run an “installer”).
Motivation
The idea here is to allow for automated systems to:
Easily obtain a python binary, that can be used in sandboxes / workstations / laptops / instances…
Inspect any python installation, and point out how portable it is, which shared or non-standard libraries it is using
Installation
portable-python is a regular python CLI, it can be installed with:
pickley install portable-python portable-python --help portable-python inspect /usr/bin/python3
Or pipx:
pipx install portable-python portable-python inspect /usr/bin/python3
Using pip install (a CI builder would probably do this):
/usr/bin/python3 -mvenv /tmp/pp /tmp/pp/bin/python -mpip install portable-python /tmp/pp/bin/portable-python --help /tmp/pp/bin/portable-python inspect /usr/bin/python3
Supported operating systems
Portable python binaries can be built for Linux and MacOS (Intel/M1/M2).
Currently Windows is NOT supported, contributions are welcome.
Python binaries can be produced as “portable” (statically linked, can run from any folder where the binary is unpacked in), or with a --prefix (build targeted to live in a pre-determined folder, like /apps/pythonM.m)
Operating system |
Portable |
–prefix |
|---|---|---|
Linux |
✅ |
✅ |
Macos |
✅ |
✅ |
Windows |
❌ |
❌ |
Building a portable cpython
Once portable-python is installed:
Build a binary:
cd some-temp-folder portable-python build 3.9.7 ls -l dist/cpython-3.9.7-macos-arm64.tar.gz
Unpack it somewhere:
tar -C ~/tmp/versions/ -xf dist/cpython-3.9.7-macos-arm64.tar.gz ls -l ~/tmp/versions/
It’s ready to be used:
~/tmp/versions/3.9.7/bin/python --version
Note that you can use --dryrun mode to inspect what would be done without doing it:
$ portable-python --dryrun build 3.9.7 INFO selected: xz openssl gdbm (3 modules) xz:5.2.5 openssl:1.1.1k gdbm:1.18.1 INFO Platform: macos-x86_64 ... -------------- -- xz:5.2.5 -- -------------- Would download https://tukaani.org/xz/xz-5.2.5.tar.gz Would untar build/sources/xz-5.2.5.tar.gz -> build/components/xz INFO env PATH=build/deps/bin:/usr/bin:/bin INFO env MACOSX_DEPLOYMENT_TARGET=10.14 Would run: ./configure --prefix=build/deps --enable-shared=no --enable-static=yes ... ... ------------------- -- cpython:3.9.7 -- ------------------- Would download https://www.python.org/ftp/python/3.9.7/Python-3.9.7.tar.xz Would untar build/sources/Python-3.9.7.tar.xz -> build/components/cpython ... Would run: ./configure --prefix=/ppp-marker/3.9.7 --enable-optimizations ... Would run: /usr/bin/make Would run: /usr/bin/make install DESTDIR=build ... Would tar build/3.9.7 -> dist/cpython-3.9.7-macos-x86_64.tar.gz
CLI reference
Main entry point:
portable-python [OPTIONS] COMMAND [ARGS]
Global options:
--config PATH: Config file (default: portable-python.yml)
--quiet: Turn off DEBUG logging
--dryrun / -n: Show what would be done
--target PLATFORM: Override detected platform (for testing)
build <PYTHON_SPEC> - Build a portable Python binary:
portable-python build 3.13.2 -m openssl,zlib
--modules, -m CSV: External modules to include
--prefix, -p PATH: Use --prefix (non-portable)
build-report [PYTHON_SPEC] - Show module status and what will be compiled:
--modules, -m CSV: Specific modules to check
Validates that modules can be built
inspect <PATH> - Check if a Python installation is portable:
portable-python inspect /usr/bin/python3
--modules, -m MODULES: Which modules to inspect
--verbose, -v: Show full .so report
--prefix, -p: Built with --prefix (not portable)
--skip-so, -s: Don’t check all .so files
list [FAMILY] - List available versions (default: cpython):
portable-python list cpython
--json: Output as JSON
diagnostics - Show system diagnostics
recompress <PATH> <EXT> - Re-compress existing binary tarball (for comparing compression sizes)
lib-auto-correct <PATH> - Auto-correct exes/libs to use relative paths:
--commit: Actually perform changes (dryrun by default)
--prefix, -p PATH: Expected --prefix from build
Library
Portable Python can be used as a python library to invoke builds, or inspect an installation.
Invoke a build from python code:
from portable_python import BuildSetup
setup = BuildSetup("cpython:3.9.7")
setup.compile()
Invoke an inspection from python code:
from portable_python.inspector import PythonInspector
inspector = PythonInspector("/usr/bin/python3")
print(inspector.represented())
problem = inspector.full_so_report.get_problem(portable=True)
if problem:
print("oops, it is not portable!: %s" % problem)
From source, contributions welcome!:
git clone https://github.com/codrsquad/portable-python.git cd portable-python python3 -mvenv .venv .venv/bin/pip install -r requirements.txt -r tests/requirements.txt .venv/bin/pip install -e . .venv/bin/portable-python --help .venv/bin/portable-python inspect /usr/bin/python3 tox -e py311 tox -e style
Build folder structure
portable-python uses this file structure (build/ and dist/ folders configurable):
build/
ppp-marker/3.9.7/ # Full installation (after build completes)
components/ # Builds of statically compiled extension modules are here
deps/ # --prefix=.../deps passed to all component ./configure scripts
sources/
openssl-1.1.1k.tar.gz # Downloaded artifacts (downloaded only once)
dist/
cpython-3.9.7-macos-arm64.tar.gz # Ready-to-go portable binary tarball
Guiding principles
Focuses on just one thing: compile a portable python, and validate that it is indeed portable, produce outcome in (configurable) ./dist/ folder and that’s it
No patches: C compilation is done as simply as possible without modifying the upstream source code. Rely solely on the make/configure scripts, typically via stuff like --enable-shared=no
Builds are validated, an important part of the effort was to write up code that is able to inspect a python installation and detect whether it is portable or not (and why not if so).
Only the last few non-EOL versions of python are supported (no historical stuff)
As time goes on, the code of this tool will evolve so that the latest pythons keep building (but won’t worry that older versions still keep building)
For this repo itself:
Code is pure python, it is a CLI with one entry-point called portable-python
Can be ran in a debugger
100% test coverage, has a --dryrun mode to help with testing / debugging / seeing what would be done quickly
No shell scripts (those are hard to maintain/test/debug)
Can be pip install-ed and reused
1 maintainer
Release files for portable-python 2.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| portable_python-2.0.2.tar.gz | 84.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| portable_python-2.0.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 129.0 kB
Release files / portable_python-2.0.2.tar.gz
| Download URL | portable_python-2.0.2.tar.gz |
|---|---|
| Size | 84.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5aedefe9e468495d1bdfb3d0ff48df094730a7070138ad397f310c0955fe8d9a
|
|
BLAKE2b-256 checksum How to use checksums |
9330460690cd15d5ec38ff0dd895c9e25a86565c8d39914a925712f175dab768
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 20, 2026.
Transparency logRelease files / portable_python-2.0.2-py3-none-any.whl
| Download URL | portable_python-2.0.2-py3-none-any.whl |
|---|---|
| Size | 44.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e8dcc008b4fa7322ab8a44acf43ef43b3895d83cf30307d0472ce6188b3fbd64
|
|
BLAKE2b-256 checksum How to use checksums |
3cb20a1757be9c018cd16760ee50213d1ef61cfab8aad72179584c86da85a130
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 20, 2026.
Transparency log
