{"id":16027541,"url":"https://github.com/followtheprocess/py","last_synced_at":"2025-10-21T22:31:24.069Z","repository":{"id":39711128,"uuid":"427412804","full_name":"FollowTheProcess/py","owner":"FollowTheProcess","description":"(Experimental) port of the python-launcher to Go.","archived":true,"fork":false,"pushed_at":"2024-08-26T13:05:39.000Z","size":1601,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-05T04:41:20.638Z","etag":null,"topics":["command-line-tool","go","python"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FollowTheProcess.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-12T15:44:36.000Z","updated_at":"2024-08-28T07:05:11.000Z","dependencies_parsed_at":"2023-02-18T23:15:53.681Z","dependency_job_id":"84abc921-9bc5-4b20-b02c-11e87331a477","html_url":"https://github.com/FollowTheProcess/py","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/FollowTheProcess/py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FollowTheProcess%2Fpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FollowTheProcess%2Fpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FollowTheProcess%2Fpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FollowTheProcess%2Fpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FollowTheProcess","download_url":"https://codeload.github.com/FollowTheProcess/py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FollowTheProcess%2Fpy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280347716,"owners_count":26315364,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line-tool","go","python"],"created_at":"2024-10-08T20:22:14.674Z","updated_at":"2025-10-21T22:31:23.705Z","avatar_url":"https://github.com/FollowTheProcess.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# py\n\n[![License](https://img.shields.io/github/license/FollowTheProcess/py)](https://github.com/FollowTheProcess/py)\n[![Go Report Card](https://goreportcard.com/badge/github.com/FollowTheProcess/py)](https://goreportcard.com/report/github.com/FollowTheProcess/py)\n[![GitHub](https://img.shields.io/github/v/release/FollowTheProcess/py?logo=github\u0026sort=semver)](https://github.com/FollowTheProcess/py)\n[![CI](https://github.com/FollowTheProcess/py/workflows/CI/badge.svg)](https://github.com/FollowTheProcess/py/actions?query=workflow%3ACI)\n\n (Approximate) port of Brett Cannon's [python-launcher] for Unix to Go, with a few tweaks 😉\n\n* Free software: MIT License\n\n## Project Description\n\n**Description of the original [python-launcher]:**\n\n\u003e *Taken directly from the official [README]*\n\nLaunch your Python interpreter the lazy/smart way!\n\nThis project is an implementation of the `py` command for Unix-based platforms\n(with some potential experimentation for good measure 😉).\n\nThe goal is to have `py` become the cross-platform command that Python users\ntypically use to launch an interpreter while doing development. By having a\ncommand that is version-agnostic when it comes to Python, it side-steps\nthe \"what should the `python` command point to?\" debate by clearly specifying\nthat upfront (i.e. the newest version of Python that can be found). This also\nunifies the suggested command to document for launching Python on both Windows\nas Unix as `py` has existed as the preferred\n[command on Windows](https://docs.python.org/3/using/windows.html#launcher)\nsince 2012 with the release of Python 3.3.\n\nTypical usage would be:\n\n``` shell\npy -m venv .venv\npy ...  # Normal `python` usage.\n```\n\nThis creates a virtual environment in a `.venv` directory using the latest\nversion of Python installed. Subsequent uses of `py` will then use that virtual\nenvironment as long as it is in the current (or higher) directory; no\nenvironment activation required (although the Python Launcher supports activated\nenvironments as well)!\n\nA non-goal of this project is to become the way to launch the Python\ninterpreter _all the time_. If you know the exact interpreter you want to launch\nthen you should launch it directly; same goes for when you have\nrequirements on the type of interpreter you want (e.g. 32-bit, framework build\non macOS, etc.). The Python Launcher should be viewed as a tool of convenience,\nnot necessity.\n\n### Why are you reimplementing it in Go?\n\n* I don't know, fun I guess?\n* I love the original [python-launcher] and I love Go, so why not combine them!\n* Learning and stuff\n\n### What's different about this one vs the original?\n\nInitially, I wanted to do a 100% pure port copying the functionality of the original [python-launcher] exactly.\n\nThen I realised that's boring and pointless because why wouldn't I just use the original? It's written really well, easy to understand,\nis fast to launch, 100% test coverage etc etc.\n\nSo I thought why not tweak it a little bit?\n\nAs a result, this version behaves slightly differently in a few ways:\n\n1. It won't let you do anything with `python2`, because it's deprecated and using it is naughty! In fact, it completely ignores any python2 interpreters it finds, so if you use this `py` there is 0 chance of accidentally launching `python2`. You're welcome macOS users!\n2. It won't climb the file tree looking for a `.venv` in any parent directory, it only looks in `cwd` (personally I only ever really use python in a virtual environment when I'm actively working on a python project, and 99% of the time for that I'm sitting in the project root where the `.venv` is anyway)\n3. The change above allows this one to easily support both virtual environments named `.venv` **and** `venv` (although `.venv` will be preferred)\n\n## Installation\n\nThere are binaries published in the [GitHub releases] section, and a homebrew formula:\n\n```shell\nbrew tap FollowTheProcess/homebrew-tap\n\nbrew install FollowTheProcess/homebrew-tap/py\n```\n\n## Quickstart\n\n### Launch the most appropriate python\n\n```shell\npy ...\n```\n\n### Launch the latest python3 on `$PATH`\n\n```shell\npy -3 ...\n```\n\n### Launch an exact version\n\n```shell\npy -3.10 ...\n```\n\n### Debugging\n\nIf you want to see what `py` is doing to find your python, set the `PYLAUNCH_DEBUG` environment variable to 1 (or anything really, the value doesn't matter) before running `py`.\n\nYou will see something like this:\n\n![demo](https://github.com/FollowTheProcess/py/raw/main/docs/img/demo.png)\n\n## Control Flow\n\nAs previously mentioned, this experimental port behaves slightly differently than the original [python-launcher]. The adjusted control flow diagram is shown below:\n\n![control_flow](https://raw.githubusercontent.com/FollowTheProcess/py/main/docs/control_flow/control_flow.svg)\n\n## Benchmarks\n\nAlthough I've not made any special efforts to optimise `py`, it is very close to the original [python-launcher] in terms of performance:\n\n![comparison](https://raw.githubusercontent.com/FollowTheProcess/py/main/docs/img/comp.png)\n\n* **Left:** This version of `py`, written in Go\n* **Right:** The original [python-launcher] written in Rust\n\n## FAQ\n\n### Does this version still work with [Starship] and display the Python version?\n\n**Short answer:** Yes! :tada: If you already have [Starship] set up for the original [python-launcher], this one should work just fine!\n\nTo set it up:\n\nAdd the following to your [Starship configuration file]:\n\n```TOML\n[python]\npython_binary = [\"py\"]\n# The following isn't necessary, but convenient.\ndetect_folders = [\".venv\"]\n```\n\n![Starship virtual env demo](https://github.com/FollowTheProcess/py/raw/main/docs/img/starship_demo.png)\n\nBy using the Launcher with Starship, your prompt will tell you which Python version will be used if you run `py`. Since the Launcher supports virtual\nenvironments, the prompt will properly reflect both what global install of Python will be used, but also the local virtual environment.\n\n### What about pyenv, does this version work with that too?\n\n**Short answer:** Again, yes!\n\nIf you're using [pyenv] to manage your Python versions, you'll want to set the version the Launcher uses to the pyenv [global version].\n\nAdd this line to your `.zshrc` or `.bashrc` file:\n\n```shell\nexport PY_PYTHON=$(head -n 1 $(pyenv root)/version | cut -d \".\" -f 1,2)\n```\n\nOr this line to your `~/.config/fish/config.fish` file:\n\n```fish\nset -gx PY_PYTHON (head -n 1 (pyenv root)/version | cut -d \".\" -f 1,2)\n```\n\n[python-launcher]: https://github.com/brettcannon/python-launcher\n[README]: https://github.com/brettcannon/python-launcher/blob/main/README.md\n[Github releases]: https://github.com/FollowTheProcess/py/releases\n[Starship]: https://starship.rs/\n[Starship configuration file]: https://starship.rs/config/\n[pyenv]: https://github.com/pyenv/pyenv\n[global version]: https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-global\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffollowtheprocess%2Fpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffollowtheprocess%2Fpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffollowtheprocess%2Fpy/lists"}