# venv-stack
`venv-stack` is a lightweight PEP 668–compliant tool for *layered* Python virtual environments.
It lets you assemble project-specific venvs by linking multiple "base" environments,
so heavy dependencies (e.g. PyTorch) live in a shared base instead of being re-installed per-project.
## Features
- **Layered Environments**
Create project virtual environments that symlink into one or more named base venvs
(no redundant copies of large packages).
- **PEP 668 Compliance**
Never require `--break-system-packages`—you stay safe from system-wide pip installs.
- **Simple CLI**
- `venv-stack base <name>`: create a named base env
- `venv-stack project [path] <bases>`: create a project env in `path/.venv`
- `venv-stack link <base> <project>`: add another base to an existing project
- `venv-stack list`: list all known venvs
- `venv-stack activate <name>`: activate a base virtual environment. If no name is given, activate the current project environment.
- `venv-stack export [project_path] [output_file]`: export installed packages to a file
- `venv-stack sync <requirements_file> [project_path]`: install packages from a `requirements.txt` into the project venv
- `venv-stack list-packages [name]`: list installed packages in a specific venv or all venvs if no name is given.
## Installation
```bash
pip install venv-stack
```
(Alternatively, clone and pip install ..)
## Usage
```bash
# 1. Create shared bases
venv-stack base common # e.g. numpy, pandas, scipy
venv-stack base ml # e.g. torch, tensorflow
# 2 Activate the base venv, install packages
venv-stack activate common
pip install numpy pandas scipy torch tensorflow
# 3. Create a project venv that layers both
cd my-project
venv-stack project . common,ml
# 4. Activate
venv-stack activate # activates the current project if no name is given
# 5. Install project‑specific deps
pip install fastapi uvicorn
# 6. Export installed packages
venv-stack export [project_path] [output_file]
# e.g. venv-stack export . requirements.txt
# 7. Sync from a requirements file
venv-stack sync [requirements.txt] [project_path]
# e.g. venv-stack sync requirements.txt .
# 8 List all virtual environments
venv-stack list
# 9 List all installed packages in a venv
venv-stack list-packages [name]
# 10 List all packages installed in all virtual environments
venv-stack list-packages
```
## Commands
| Command | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------- |
| `venv-stack base <name>` | Create a named base environment |
| `venv-stack project [path] <bases>` | Create a stacked project env at `path/.venv` |
| `venv-stack link <base> <project>` | Add a base to an existing project venv |
| `venv-stack list` | List all known base & project virtual environments |
| `venv-stack activate <name>` | Activate the given base environment `<name>` |
| `venv-stack export [project_path] [output_file]` | Export the stacked project venv’s installed packages (`pip freeze`) to a file |
| `venv-stack sync <requirements_file> [project_path]` | Install packages from a `requirements.txt` into the project venv |
| `venv-stack list-packages [name]` | List installed packages in a specific venv or all venvs if no name is given |
## Activate not working with your terminal?
You can update the shells.py file to add your shell:
```python
# needed in order for the activate command to work properly.
# If you are using a different shell, you may need to adjust the candidates accordingly.
shells = {
"bash": {
"flags": lambda tmp_profile_path: ["--rcfile", f"{tmp_profile_path}", "-i"],
"rc": [".bashrc", ".bash_profile", ".profile"]
},
"zsh": {
"env": lambda tmp_profile_path: f"ZDOTDIR={tmp_profile_path.parent}",
"flags": ["-i"],
"rc": [".zshrc", ".zprofile"]
},
}
```
## Contributing
1. Fork the repo
2. Create a feature branch (git checkout -b feature/foo)
3. Commit your changes (git commit -am 'Add foo')
4. Push and open a PR
Raw data
{
"_id": null,
"home_page": null,
"name": "venv-stack",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "virtualenv, venv, python, PEP 668, environment management",
"author": null,
"author_email": "Ata Hak\u00e7\u0131l <ignis@ignis.wtf>",
"download_url": "https://files.pythonhosted.org/packages/dc/c5/77fa485ee2b04410d56e652d0d8ac806e8fdf539966261b3120db266a05e/venv_stack-1.0.0.tar.gz",
"platform": null,
"description": "# venv-stack\n\n`venv-stack` is a lightweight PEP 668\u2013compliant tool for *layered* Python virtual environments. \nIt lets you assemble project-specific venvs by linking multiple \"base\" environments, \nso heavy dependencies (e.g. PyTorch) live in a shared base instead of being re-installed per-project.\n\n## Features\n\n- **Layered Environments** \n Create project virtual environments that symlink into one or more named base venvs \n (no redundant copies of large packages).\n\n- **PEP 668 Compliance** \n Never require `--break-system-packages`\u2014you stay safe from system-wide pip installs.\n\n- **Simple CLI** \n - `venv-stack base <name>`: create a named base env \n - `venv-stack project [path] <bases>`: create a project env in `path/.venv` \n - `venv-stack link <base> <project>`: add another base to an existing project \n - `venv-stack list`: list all known venvs \n - `venv-stack activate <name>`: activate a base virtual environment. If no name is given, activate the current project environment.\n - `venv-stack export [project_path] [output_file]`: export installed packages to a file\n - `venv-stack sync <requirements_file> [project_path]`: install packages from a `requirements.txt` into the project venv\n - `venv-stack list-packages [name]`: list installed packages in a specific venv or all venvs if no name is given.\n\n\n\n\n## Installation\n\n```bash\npip install venv-stack\n```\n(Alternatively, clone and pip install ..)\n\n## Usage\n\n```bash\n# 1. Create shared bases\nvenv-stack base common # e.g. numpy, pandas, scipy\nvenv-stack base ml # e.g. torch, tensorflow\n\n# 2 Activate the base venv, install packages\nvenv-stack activate common\npip install numpy pandas scipy torch tensorflow\n\n# 3. Create a project venv that layers both\ncd my-project\nvenv-stack project . common,ml\n\n# 4. Activate\nvenv-stack activate # activates the current project if no name is given\n\n# 5. Install project\u2011specific deps\npip install fastapi uvicorn\n\n# 6. Export installed packages\nvenv-stack export [project_path] [output_file]\n# e.g. venv-stack export . requirements.txt\n\n# 7. Sync from a requirements file\nvenv-stack sync [requirements.txt] [project_path]\n# e.g. venv-stack sync requirements.txt .\n\n# 8 List all virtual environments\nvenv-stack list\n\n# 9 List all installed packages in a venv\nvenv-stack list-packages [name]\n\n# 10 List all packages installed in all virtual environments\nvenv-stack list-packages\n```\n\n## Commands\n\n| Command | Description |\n| ---------------------------------------------------- | ----------------------------------------------------------------------------- |\n| `venv-stack base <name>` | Create a named base environment |\n| `venv-stack project [path] <bases>` | Create a stacked project env at `path/.venv` |\n| `venv-stack link <base> <project>` | Add a base to an existing project venv |\n| `venv-stack list` | List all known base & project virtual environments |\n| `venv-stack activate <name>` | Activate the given base environment `<name>` |\n| `venv-stack export [project_path] [output_file]` | Export the stacked project venv\u2019s installed packages (`pip freeze`) to a file |\n| `venv-stack sync <requirements_file> [project_path]` | Install packages from a `requirements.txt` into the project venv |\n| `venv-stack list-packages [name]` | List installed packages in a specific venv or all venvs if no name is given |\n\n\n\n## Activate not working with your terminal?\nYou can update the shells.py file to add your shell:\n```python\n# needed in order for the activate command to work properly. \n# If you are using a different shell, you may need to adjust the candidates accordingly.\nshells = {\n \"bash\": {\n \"flags\": lambda tmp_profile_path: [\"--rcfile\", f\"{tmp_profile_path}\", \"-i\"],\n \"rc\": [\".bashrc\", \".bash_profile\", \".profile\"]\n },\n \"zsh\": {\n \"env\": lambda tmp_profile_path: f\"ZDOTDIR={tmp_profile_path.parent}\",\n \"flags\": [\"-i\"],\n \"rc\": [\".zshrc\", \".zprofile\"]\n },\n}\n```\n\n## Contributing\n\n1. Fork the repo\n\n2. Create a feature branch (git checkout -b feature/foo)\n\n3. Commit your changes (git commit -am 'Add foo')\n\n4. Push and open a PR\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A layered virtual environment manager compatible with PEP 668",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/ignis-sec/venv-stack",
"Issues": "https://github.com/ignis-sec/venv-stack/issues",
"Repository": "https://github.com/ignis-sec/venv-stack"
},
"split_keywords": [
"virtualenv",
" venv",
" python",
" pep 668",
" environment management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a6b85dc8e31127b8e54a2829e159649ff5958005bffa01836c77f73f9f3a8da2",
"md5": "25508b3cd6fffc363bbe5e4761417b3c",
"sha256": "5d042cf81a11cb779c4d01360676ff7370486655ecda434bc381ff61da07966e"
},
"downloads": -1,
"filename": "venv_stack-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "25508b3cd6fffc363bbe5e4761417b3c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7559,
"upload_time": "2025-07-28T14:54:22",
"upload_time_iso_8601": "2025-07-28T14:54:22.945012Z",
"url": "https://files.pythonhosted.org/packages/a6/b8/5dc8e31127b8e54a2829e159649ff5958005bffa01836c77f73f9f3a8da2/venv_stack-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dcc577fa485ee2b04410d56e652d0d8ac806e8fdf539966261b3120db266a05e",
"md5": "0fa1b2ab1df15d29626f1846a68d9e6d",
"sha256": "ca5a8848b06ed4b448049bb055c471e32ff2a1eb34a9258a6162bee746923ff9"
},
"downloads": -1,
"filename": "venv_stack-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "0fa1b2ab1df15d29626f1846a68d9e6d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7917,
"upload_time": "2025-07-28T14:54:24",
"upload_time_iso_8601": "2025-07-28T14:54:24.539811Z",
"url": "https://files.pythonhosted.org/packages/dc/c5/77fa485ee2b04410d56e652d0d8ac806e8fdf539966261b3120db266a05e/venv_stack-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 14:54:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ignis-sec",
"github_project": "venv-stack",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "venv-stack"
}
JSON
