Let's learn about the windows embeddable portable Python distributions.
- The Windows embeddable Python distribution is a minimal, self‑contained build of Python designed to run entirely from its own directory without installation.
- This distribution does not modify system settings, environment variables, or the Windows registry.
- Its structure makes it suitable for embedding Python inside applications or distributing Python as a portable runtime.
Typical use cases
- Bundling Python with standalone software that requires a predictable runtime environment.
- Running Python scripts in isolated environments where system‑wide installations must not be affected.
- Deploying portable utilities that must operate from removable storage or restricted systems.
When the embeddable distribution is not ideal
- General development workflows that rely on pip, external packages, or virtual environments.
- Educational or experimental setups where tutorials assume a standard Python installation.
- Projects that depend on automatic module discovery and dynamic package management.
The Role of python310._pth
- The file named
python310._pthcontrols how the embeddable distribution locates and loads Python modules. - When this file is present, Python enters an isolated mode in which only the paths explicitly listed inside the file are used.
- If the file does not include the line
import site, the standard site initialization process is disabled, preventing access to site‑packages.
Typical structure of python310._pth
python310.zip
.
import siteExplanation of each entry
python310.zipspecifies the location of the standard library packaged as a zip archive..allows Python to import modules from the root directory of the distribution.import siteactivates the site module, enabling automatic loading of Lib and site‑packages.
Enabling pip and external modules
- The embeddable distribution does not load external modules unless the appropriate paths are added to
python310._pth. - To enable pip and other installed packages, the file must include the Lib and Lib\site-packages directories.
Example of a Fully Enabled python310._pth
python310.zip
.
Lib
Lib\site-packages
import siteTesting the updated configuration
python -c "import sys; print(sys.path)"Installing pip after enabling site‑packages
- Once the module paths are active, pip can be installed using standard methods.
python get-pip.pypython -m ensurepipVerifying pip
python -m pip --versionAdvantages of the embeddable distribution:
- Provides a predictable and isolated runtime environment.
- Does not interfere with system‑wide Python installations.
- Ideal for packaging Python with standalone applications.
Disadvantages of the embeddable distribution:
- pip and external modules are disabled by default.
- Requires manual configuration to behave like a standard installation.
- Not suitable for typical development workflows.
Clean, Ready‑to‑Use python310._pth File
python310.zip
.
Lib
Lib\site-packages
import siteThis will fix the embeddable distribution, let's use this source code to fix the pip tool:
import os
import urllib.request
import zipfile
import shutil
PYTHON_DIR = r"C:\python-3_10_11"
SITE = fr"{PYTHON_DIR}\Lib\site-packages"
print("[INFO] Descarc pip.zip...")
urllib.request.urlretrieve(
"https://github.com/pypa/pip/archive/refs/heads/main.zip",
"pip.zip"
)
print("[INFO] Dezarhivez pip.zip...")
with zipfile.ZipFile("pip.zip", "r") as z:
z.extractall("pip_src")
pip_src = "pip_src/pip-main/src/pip"
print("[INFO] Copiez pip în site-packages...")
target = os.path.join(SITE, "pip")
if os.path.exists(target):
shutil.rmtree(target)
shutil.copytree(pip_src, target)
print("[INFO] Creez pip.dist-info minimal...")
dist = os.path.join(SITE, "pip.dist-info")
os.makedirs(dist, exist_ok=True)
with open(os.path.join(dist, "METADATA"), "w") as f:
f.write("Name: pip\nVersion: 0\n")
print("[OK] pip instalat direct în Python.")
print("Rulează acum:")
print(" python -m pip --version")
Let's tun and test with PyQt6:
python fix_pip.py
[INFO] Descarc pip.zip...
[INFO] Dezarhivez pip.zip...
[INFO] Copiez pip în site-packages...
[INFO] Creez pip.dist-info minimal...
[OK] pip instalat direct în Python.
Rulează acum:
python -m pip --version
python -m pip --version
pip 26.2.dev0 from C:\python-3_10_11\Lib\site-packages\pip (python 3.10)
python -m pip install PyQt6
Collecting PyQt6
Downloading pyqt6-6.11.0-cp310-abi3-win_amd64.whl.metadata (2.2 kB)
...
Installing collected packages: PyQt6-Qt6, PyQt6-sip, PyQt6
Successfully installed PyQt6-6.11.0 PyQt6-Qt6-6.11.1 PyQt6-sip-13.11.1
