Skip to content

README.md

Latest commit

 

History

History
190 lines (129 loc) · 6.31 KB

README.md

File metadata and controls

190 lines (129 loc) · 6.31 KB
Raw

GhostPython

(Ghost Python – A zero‑install, fully portable Python 3.14 distribution for Windows that never touches the Registry. Ships with surgically aligned Tcl/Tk libraries (no more tk.tcl errors), a smart silent/ interactive banner, and built‑in shell commands (tree, clean, libs, clear). Run from USB, CI runners, or embedded systems. Leave no trace.)

👻 Ghost Python

High-performance · Ultra-minimal · Fully portable · Python 3.14 for Windows

Download windows App(Download App)

License: MIT

Python 3.14

Platform

Ghost Python is a surgically clean, zero‑footprint Python 3.14 distribution that runs entirely from a single folder.
It never touches the Windows Registry, never writes to System32, and eliminates the infamous Tcl/Tk tk.tcl not found errors once and for all.

Perfect for USB drives, CI runners, embedded systems, and developers who want a ghost of a setup — present when you need it, gone when you don't.

Why Ghost Python?

Problem Ghost Solution
Bloated installers, registry pollution One folder. Copy → run → delete. No traces.
_tkinter.TclError: Can't find a usable tk.tcl Binary‑aligned, pre‑linked Tcl/Tk libraries.
Cluttered terminal after import Silent during scripts, custom banner only in interactive mode.
No custom shell shortcuts Built‑in commands (tree, clean, libs, clear) in builtins.
Locked Python version Ships with Python 3.14 – fresh, minimal, portable.

Quick Start (60 seconds)

1. Download

Get the latest release from:
👉 https://github.com/DAPOWER99/GhostPython/releases

2. Extract

Unzip the archive to any location – for example:

C:\tools\GhostPython\
D:\USB\GhostPython\

3. Run

cd C:\tools\GhostPython
.\python.exe

You will see the Ghost banner (only in interactive sessions):

👻 Ghost Python 3.14 ready.
Type 'help', 'tree', 'clean', 'libs', 'clear'
>>>

4. Use as a portable environment

.\python.exe -m pip install requests
.\python.exe my_script.py

To remove Ghost Python completely — delete the folder. No uninstaller, no registry keys.

Custom Commands Reference

Ghost Python injects several helper commands directly into the builtins namespace via sitecustomize.py.
These work only in the interactive REPL and do not interfere with normal scripts.

Command Description Example
tree Display directory tree of current working directory tree or tree("C:\\projects")
clean Remove __pycache__ and .pyc files recursively clean() or clean("src/")
libs List all installed pip packages with versions libs
clear Clear terminal screen (cross‑platform) clear

All commands support optional paths/arguments and integrate seamlessly with Python’s help() system.

Architecture & Configuration

settings.config — Toggle core modules on/off

Ghost Python uses a lightweight settings.config file in the root folder to enable/disable major components at runtime.

feature of these can be disabled by changing the value to anything other than "enabled"

[Features]
Lib=enabled "libs important"

DLLs=enabled "Dlls"

tcl=enabled "Tcl folder"

Title=enabled "credits non important""

Disabling include_tcl removes tkinter entirely – useful for headless or server‑side deployments.

Smart Banner Logic

  • Interactive session → Shows the Ghost banner.
  • Script execution (python script.py) → No banner, no output.
  • Piped input → Automatically silent.

This guarantees zero noise in automation while keeping the REPL friendly.

Portability Guarantees

  • No PYTHONPATH, no PATH modifications.
  • No %APPDATA% or %LOCALAPPDATA% writes.
  • All relative paths resolved from the executable’s folder.

Use Cases

Scenario Why Ghost Python fits
USB‑based development Run Python from a flash drive on any Windows PC.
CI/CD pipelines (Windows) No admin rights, no install step.
Teaching / workshops Students download one folder – no environment issues.
Embedded / kiosk systems Minimal disk footprint, toggle‑off features.
Legacy Tcl/Tk conflict resolution Pre‑aligned libraries override system globals.

Project Structure (simplified)

GhostPython/
├── python.exe
├── python3.dll
├── settings.config
├── sitecustomize.py          # Custom commands + banner logic
├── Lib/                      # Standard library (toggle via config)
├── DLLs/                     # Core DLLs (toggle via config)
├── tcl/                      # Tcl/Tk runtime (toggle via config)
├── Scripts/                  # pip, wheel, etc.
└── Tools/                    # Optional (toggle via config)

Building from source (for maintainers)

Ghost Python is built from an official Python 3.14 source tarball with:

  • --disable-posix-shm (Windows portability)
  • --enable-shared (DLL separation)
  • Custom _tkinter compilation with bundled Tcl/Tk 8.6.

See BUILD.md for the exact patchset and Windows SDK requirements.

License

MIT License – use freely, commercially or otherwise.
Attribution appreciated but not required.

Contributing

Issues and PRs are welcome at:
🔗 https://github.com/DAPOWER99/GhostPython

Focus areas:

  • Reducing DLL dependencies further
  • Adding settings.config toggles for more sub‑libraries
  • Supporting Windows on ARM (WoA)

Acknowledgments

Built with respect for the Python Software Foundation, the Tcl/Tk community, and every depressed developer who has ever debugged tk.tcl at 2 AM.

Ghost Python – leave no trace, solve real problems.