📦 Script-offline-libery

Offline Python Package Installer & Virtual Environment Manager

A menu-driven tool for offline package management in Python projects. Ideal for servers or machines with no Internet access: download everything once on a connected machine, copy the folder to the offline machine, then install and run entirely offline — no network required.

---

📑 Table of Contents

• Features
• Project Structure
• Requirements
• Usage
• Typical Workflow
• How It Works
• Adding Your Own Packages
• Troubleshooting
• Notes
• Contributing
• License

✨ Features

• Offline Download & Installation — Download package wheels once into a local folder (libay), then install them on any machine without an Internet connection.
• Python Version Selection — Choose 3.9, 3.10, 3.11, 3.12, or 3.13; the tool picks package versions suited to that version.
• Virtual Environment Management — Create a venv and populate it with the downloaded packages.
• Run Your App — Launch a Python script inside the virtual environment in a new terminal window (PowerShell on Windows, gnome-terminal on Linux).
• Smart Skipping — Already-downloaded packages are detected and skipped, so re-running the downloader is fast and safe.
• Cross-Platform — Automatically detects Windows vs. Linux and adjusts behavior (e.g., uvloop is skipped on Windows since it is Linux-only).

📁 Project Structure

.
├── installer.py   # Main menu-driven installer / venv manager
├── packges.py     # PACKAGES dict: recommended versions per Python version
├── libay/         # (created at runtime) Offline package downloads
└── venv/          # (created at runtime) Virtual environment

🔧 Requirements

• Python 3.9 or newer (package recommendations are available for 3.9–3.13).
• pip (included with Python).
• Windows: PowerShell (used to launch your script inside the venv).
• Linux: a terminal emulator such as gnome-terminal.

🚀 Usage

1. Download the script files — save installer.py and packges.py to your working directory.

2. Run the installer:

   python installer.py

3. Choose an option from the menu:

   Option	Action
   0	Download packages into the libay folder (requires Internet — do this once)
   1	List the files already downloaded in libay
   2	Install the downloaded packages offline (system Python)
   3	Create a virtual environment (venv) and install packages into it
   4	Run a Python script inside the virtual environment (opens a new terminal window)
   5	Set the target Python version (3.9, 3.10, 3.11, 3.12, or 3.13)
   q	Quit

🔄 Typical Workflow

1. Run python installer.py and pick option 5 to select your target Python version.
2. Pick option 0 to download all packages (and their wheels) into libay — this is the only step that needs Internet.
3. Copy the whole project folder (including libay) to the offline machine.
4. Pick option 2 or 3 to install offline into the system Python or into a fresh venv.
5. Pick option 4 to run your application inside the virtual environment.

Tip: The download (option 0) and the install (options 2/3) do not have to happen on the same machine — that is the whole point. Just make sure both machines use the same OS and Python version, otherwise the downloaded wheels may not be compatible.

⚙️ How It Works

• Version pinning — packges.py maps every package to a recommended version per Python version. Entries marked latest are downloaded unpinned.
• Offline installs — All installs use pip install --no-index --find-links libay, so pip never touches the network.
• pip self-upgrade — Before an offline install, the tool checks the current pip version and upgrades it from the local libay folder if a pinned version is available.
• Skipping already-downloaded files — The downloader checks libay first and skips packages whose files already exist there.

➕ Adding Your Own Packages

Open packges.py and add an entry to the PACKAGES dictionary. Each key is a package name; each value maps a Python version to a pinned version or latest:

PACKAGES = {
    # ... existing packages ...
    "requests": {"3.9": "2.31.0", "3.10": "latest", "3.11": "latest", "3.12": "latest", "3.13": "latest"},
}

• Use a pinned version (e.g. "2.31.0") when you need reproducible installs on a specific Python version.
• Use "latest" to let pip resolve the newest compatible version at download time.
• Remember to add entries for all Python versions you plan to target.

🛠️ Troubleshooting

Problem	Solution
gnome-terminal not found on Linux	The runner only launches gnome-terminal. Edit run_app_in_venv() in installer.py to use your terminal emulator (e.g. kitty, konsole, xterm).
pip cannot find a package during offline install	The wheel is missing from libay, or it was downloaded for a different Python version / OS. Re-download on a machine matching the offline machine.
A package fails to download	Check your Internet connection and the package name spelling in packges.py. Failed downloads are skipped and reported; re-run option 0 to retry.
pkg_resources deprecation warning	Harmless warning on newer Python/setuptools versions — the pip version check still works.
Wheels downloaded but install fails on the offline machine	Make sure both machines have the same OS, architecture, and Python version — wheels are platform-specific.

📝 Notes

• uvloop is Linux-only; it is skipped automatically on Windows during both download and install.
• Linux terminal — The script launches a new gnome-terminal window. If you use another terminal emulator (kitty, konsole, xterm, …), adjust run_app_in_venv() in installer.py.
• Offline first run — On a machine with no Internet, start with option 2 or 3 (option 0 requires connectivity).
• The libay and venv folders are generated at runtime and do not need to be committed to version control.

🤝 Contributing

Contributions are welcome! Feel free to submit issues or pull requests for further improvements.

📄 License

Distributed under the MIT License.