Description

kuankuan2007

opened on Sep 10, 2025

Issue body actions

Background

Currently, for offline installation of a Python version using pymanager, the recommended workflow is as follows:

1. Use the --download option to download the ZIP package into a directory.
2. Generate an index.json file in that directory.
3. When installing, use the --source option to specify the corresponding index.json.

While this method works, it introduces unnecessary steps, especially since the ZIP package or directory often contains all the information needed for installation.

Proposed Improvement

Why can't we install a Python version directly from a ZIP package or directory, without requiring an index.json?

For modern Python packages generated from PC/layout (with the --include-install-json parameter enabled) they already have __install__.json, and the resulting ZIP or directory already includes everything necessary for installation. In these cases, pymanager should be able to install directly from the package or directory.

Use Case

For example, when I compiled a CPython version by myself and packaged it using PC/layout, the output result would either be a directory or a ZIP file package. To install using pymanager, I had to manually create an index.json file, which was neither convenient nor beneficial for users.

Another typical scenario is when I use the --download command to fetch a Python package ZIP file on a device with internet access, and then copy that ZIP file to a target device that cannot connect to the internet.

On the target device, the local directory only contains this specific ZIP file package. Even if there are multiple packages, they are all stored in a unified naming format of pythoncore-3.xx-(32|64)-3.xx.xx. In this case, the user does not care about the different Python versions in the directory, and does not need to use index.json for indexing or matching version tag from command-line parameters. The intention is clear: I only want to install the contents of this ZIP file package

Requiring the use of index.json in such a case introduces unnecessary complexity and steps for a straightforward, single-package installation. Supporting direct installation from the ZIP package would greatly improve the user experience, especially for offline and isolated environments.

Suggestion

Please consider supporting direct installation from a ZIP package or directory, especially when it already contains all required installation files (including __install__.json). This will simplify the workflow for offline installations and make it easier for users compiling their own Python builds.

Reacted by Steve Dower and Zhikang Yan

Activity

1. kuankuan2007

   added

   enhancementNew feature or requestNew feature or request

   on Sep 10, 2025
2. zooba commented on Sep 10, 2025

   

   zooba

   on Sep 10, 2025

   Member

   More actions

   Yep, this would be a good feature. Especially for the installing your own build case you mentioned.
3. zooba

   added

   help wantedExtra attention is neededExtra attention is needed

   on Sep 10, 2025
4. zooba

   self-assigned this

   on Sep 15, 2025
5. zooba

   added a commit that references this issue on Sep 15, 2025

   [WIP] Implement support for 'py install uri/path' to directly install…

   This issue will close once commit c607e7c is merged into the 'main' branch.

   c607e7c
6. zooba commented on Sep 15, 2025

   

   zooba

   on Sep 15, 2025

   Member

   More actions

   FTR, I started working on this and it really upsets a lot of the existing logic (mostly the logic for trimming extra log output). Chances are it needs to be untangled a bit anyway so we can (eventually) support multiple platforms, but I'm putting my work on hold for a bit.
7. GadgetSteve commented on Oct 21, 2026

   

   GadgetSteve

   on Oct 21, 2026

   More actions

   Working in an area where offline (air-gapped) installs are essential I have to agree that this would be an important step to take, especially with the plans to no longer provide an installer build in the near future.

   I am just wondering if there might not be a simpler approach than trying to get the install to work without the index.json - that would be for the py install --download command to automatically generate an index.json or extend any existing one in the same directory as the zip file.

   Possibly the python build process could also be extended to also output a similar file/fragment.
8. GadgetSteve commented on Oct 21, 2026

   

   GadgetSteve

   on Oct 21, 2026

   More actions

   On testing I see that the py install --download does (re-)generate an index.json so it is only the python build process that really needs to be updated, (for those that build python from scratch).

   Since the code is already there it might be worth considering adding an option, (or documenting if it exists), to (re-)generate the index.json given a path with one, or more, zip files in.
9. zooba commented on Oct 21, 2026

   

   zooba

   on Oct 21, 2026

   Member

   More actions

   it is only the python build process that really needs to be updated, (for those that build python from scratch).

   This would likely be an extra script in the main CPython repo (possibly an option to PC/layout).

   For the record, the __install__.json already generated by the PC/layout tool is what goes into the index.json more or less directly (the URL likely needs updating to point to the right destination). Most of the complexity we deal with for upstream releases comes from putting entries in the right order, since py install <tag> is going to select the first entry that can be installed for that tag, with only a few caveats for prereleases and our split index (so that most users download a small JSON file rather than the complete one).

   py install --download doesn't order the entries, IIRC, but just adds each new version to the end (you can py install --download <same dir> multiple times, or specify multiple tags). That may become a limitation for some people, but it is just a plain JSON file either way, so honestly I'd rather see people develop and share helper scripts for manipulating them than have everyone wait for features to be implemented upstream. If we wanted everyone to wait for us, we'd have used a proprietary format that's hard to modify, rather than something that's easy to just hack around with yourself to do what you need.

   If you want a script that opens a set of ZIP files, reads __install__.json out of each, and writes them to a JSON file under the "versions": [] property, don't wait for us. You can just do things :)

   Reacted by Steve (Gadget) Barnes

Issue actions