{"id":20002231,"url":"https://github.com/jzombie/pipper","last_synced_at":"2025-09-05T06:32:04.157Z","repository":{"id":214918341,"uuid":"737677674","full_name":"jzombie/pipper","owner":"jzombie","description":"Pipper makes working with pip and virtual environments easier.","archived":false,"fork":false,"pushed_at":"2025-02-11T20:40:53.000Z","size":57,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-04T15:40:54.384Z","etag":null,"topics":["conda","pip","poetry","pyenv-virtualenv","python","python-package-management","python-requirements","unittest","virtual-environments"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/jzombie.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,"zenodo":null}},"created_at":"2024-01-01T03:28:49.000Z","updated_at":"2025-02-12T01:45:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"f9ccb658-bf7b-4f7f-8dc0-f27667999da9","html_url":"https://github.com/jzombie/pipper","commit_stats":{"total_commits":27,"total_committers":1,"mean_commits":27.0,"dds":0.0,"last_synced_commit":"9bab8a0a1f85f0b3745e2fa236dd708f34893505"},"previous_names":["jzombie/pipper"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jzombie/pipper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzombie%2Fpipper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzombie%2Fpipper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzombie%2Fpipper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzombie%2Fpipper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jzombie","download_url":"https://codeload.github.com/jzombie/pipper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzombie%2Fpipper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273722737,"owners_count":25156300,"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-09-05T02:00:09.113Z","response_time":402,"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":["conda","pip","poetry","pyenv-virtualenv","python","python-package-management","python-requirements","unittest","virtual-environments"],"created_at":"2024-11-13T05:20:09.908Z","updated_at":"2025-09-05T06:32:04.094Z","avatar_url":"https://github.com/jzombie.png","language":"Shell","readme":"# Pipper - PIP Python Environment Runner\n_(A Simple `pip` Wrapper Written in Bash)_\n\n[![CI](https://github.com/jzombie/pipper/workflows/CI/badge.svg)](https://github.com/jzombie/pipper/actions/workflows/ci.yml)\n[![ShellCheck](https://github.com/jzombie/pipper/workflows/ShellCheck/badge.svg)](https://github.com/jzombie/pipper/actions/workflows/shellcheck.yml)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/b83c0ce7f8924db99be96d045ffc4503)](https://app.codacy.com/gh/jzombie/pipper/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n\n![Python Logo](https://www.python.org/static/community_logos/python-logo-master-v3-TM.png)\n\n`Pipper` is a lightweight `pip` wrapper, using very minimal code written in `Bash`, which simplifies creating `Python` virtual environments, installing packages, and freezing `requirements.txt`.\n\nIt does not aim to do anything more than that.\n\n```bash\n$ pipper shell\nLaunching a sub-shell with the virtual environment activated...\n\nHello from pipper shell!\n\n[pipper-shell python 3.12.5] /Volumes/MyVolume/Projects/my_project $\n```\n\n## Why Not Use Poetry (or something else)?\n\n`Pip` is standard in `Python`, but some of its basic functionalities are hard to use. `Pipper` was written to help me understand `pip` a little bit more without introducing so much functionality that this project would become hard to maintain.\n\nI got a distaste for using `Poetry` when trying to use it to install `tensorflow` on my Mac without hacking around with dependency configuration: https://github.com/python-poetry/poetry/issues/8271.  I also don't like the fact that `Poetry` doesn't use `requirements.txt`; it generally feels slower than `pip`.\n\n`Poetry` seems to be a great tool, but it should be compatible with `pip`, I believe, not try to replace it.\n\n`Pipper` does not intend to replace `pip`, and I apologize if it appears as it does.\n\n## Tested Platforms\n\n`Pipper` has been tested on the following operating systems and Python versions:\n\n- `Python 3.10 - 3.12`\n- `Ubuntu 22 \u0026 24`\n- `macOS Ventura 13.6`\n\n## Commands/Features\n\nNote: All commands can be run from *outside* of the virtual environment and will automatically launch as needed.\n\n- `pipper create`: Create a Python virtual environment. If you have more than one version of Python installed locally, you can do `pipper create python[python-version]`. (Note: Pipper uses the `venv` directory in your project and supports one environment at a time.)\n- `pipper shell`: Drops into a Bash sub-shell already configured with the virtual environment.\n- `pipper install`: Install ALL packages from a `requirements.txt` file (Note: if wanting to install a *specific* package, use `pip install [package-name]` instead).\n- `pipper freeze`: Freeze installed packages to update the `requirements.txt` file.\n- `pipper uninstall`: Uninstall ALL packages listed in the `requirements.txt` file (Note: if wanting to uninstall a *specific* package, use `pip uninstall [package-name]` instead).\n- `pipper run`: Run a Python script within the virtual environment.\n- `pipper test`: Run unit tests within the virtual environment (via `unittest`).\n\n## Getting Started\n\nNote: `Pipper` requires a `Bash` shell.\n\n`Pipper` can be **used without installation** by running the `pipper.sh` script directly. However, if you want to make it globally accessible, you can install it as follows:\n\n### Installation [Optional]\n\n1. Clone the `Pipper` repository to your local machine:\n\n   ```bash\n   git clone https://github.com/jzombie/pipper.git\n   ```\n\n2. Navigate to the `Pipper` directory:\n\n   ```bash\n   cd pipper\n   ```\n\n3. Install `Pipper` globally using the `install` command:\n\n   ```bash\n   sudo install -m 755 pipper.sh /usr/local/bin/pipper\n   ```\n\n  _(Or replace `/usr/local/bin/` with a directory of your choice that is in your system's PATH.)_\n\nNow, you can use Pipper as a global command by typing `pipper` in your terminal.\n\n### Uninstall\n\n```bash\nsudo rm /usr/local/bin/pipper\n```\n\n_(Or replace `/usr/local/bin/` with the directory where you installed it.)_\n\n### Custom Python Environment\n\nTo create a virtual environment with a custom Python interpreter, use the create command followed by the path or alias of the desired Python version. For example:\n\n```bash\npipper create python3.8\n```\n\nThis command will attempt to create a virtual environment using Python 3.8, if it's available on your system.\n\n### Running Python Scripts\n\nIf you are **inside the virtual environment**, you can run a `Python` script as usual:  \n\n```bash\npython script.py\n```\n\nHowever, if you are **outside the virtual environment**, you can use `pipper run` to automatically activate the environment and execute the script:  \n\n```bash\npipper run script.py\n```\n\nThis ensures that the script runs within the virtual environment, whether you are inside or outside of it.\n\n### Running Python Unit Tests (via `unittest`)\n\nIf you are using the `unittest` framework, you can run your project's unit tests using the `pipper test` command:\n\n```bash\npipper test\n```\n\n_Note: This command can be invoked whether inside or outside of the virtual environment, and will ensure tests are run within your virtual environment._\n\nBy default, this command will discover and run unit tests located in the 'test' directory with filenames matching the pattern 'test*.py'.\n\nYou can also specify a custom source directory and file pattern using optional arguments as follows:\n\n```bash\npipper test [source_directory] [file_pattern]\n```\n\nFor example, to run tests located in the 'tests' directory with filenames ending in '_test.py', you can use:\n\n```bash\npipper test tests '*_test.py'\n```\n\nNote: You can also do a \"dry run\" to just echo the command it \"would have\" generated via:\n\n```bash\npipper test-dry-run\n\n# Produces:\n# source venv/bin/activate \u0026\u0026 python -m unittest discover -s 'test' -p 'test*.py'\n```\n\n### Example Workflow\n\nHere's an example of how to use `Pipper` to manage a `Python` project:\n\n1. Create a virtual environment.\n\n2. Activate the virtual environment (follow the displayed instructions).\n\n3. Install project dependencies from a `requirements.txt` file.\n\n4. As you work on your project and install new packages, periodically freeze the requirements.\n\n## Docker [Optional] (for a quick `Python` w/ `Pipper` environment)\n\n```bash\n# Build the Pipper Docker image using the Python version specified in the Dockerfile\ndocker build -t pipper .\n\n# Run an interactive Bash shell inside the container, using the Python version defined in the Dockerfile\ndocker run -it pipper\n\n# Once inside the container, you can check the active Python version:\npython --version\n# Example output:\n# Python 3.12.9\n\n# Pipper is installed locally inside the container and can be used directly:\npipper --help\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\nEnjoy using `Pipper` for managing your `Python` virtual environments and dependencies! If you encounter any issues or have suggestions for improvements, feel free to contribute to the [project on GitHub](https://github.com/jzombie/pipper).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjzombie%2Fpipper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjzombie%2Fpipper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjzombie%2Fpipper/lists"}