{"id":27969029,"url":"https://github.com/anoopkcn/zenv","last_synced_at":"2026-04-30T02:38:02.173Z","repository":{"id":290152793,"uuid":"972916525","full_name":"anoopkcn/zenv","owner":"anoopkcn","description":"Python Environment Manager for HPC and Development Systems","archived":false,"fork":false,"pushed_at":"2025-07-23T09:01:24.000Z","size":518,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-29T14:49:23.942Z","etag":null,"topics":["hpc","hpc-clusters","module","package-manager","pip","python","slurm","supercomputing","uv","zenv"],"latest_commit_sha":null,"homepage":"","language":"Zig","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/anoopkcn.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":"2025-04-25T22:21:58.000Z","updated_at":"2025-11-05T20:49:39.000Z","dependencies_parsed_at":"2025-05-07T21:08:19.214Z","dependency_job_id":"0b2e0180-4c47-47e3-8aa9-fb354065a74d","html_url":"https://github.com/anoopkcn/zenv","commit_stats":null,"previous_names":["anoopkcn/zenv"],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/anoopkcn/zenv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoopkcn%2Fzenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoopkcn%2Fzenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoopkcn%2Fzenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoopkcn%2Fzenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anoopkcn","download_url":"https://codeload.github.com/anoopkcn/zenv/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anoopkcn%2Fzenv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32452743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"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":["hpc","hpc-clusters","module","package-manager","pip","python","slurm","supercomputing","uv","zenv"],"created_at":"2025-05-07T21:08:14.049Z","updated_at":"2026-04-30T02:38:02.158Z","avatar_url":"https://github.com/anoopkcn.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zenv\n\nPython Environment Manager for HPC and Development Systems\n\n`zenv` is a command-line tool written in Zig that manages Python virtual environments, primarily designed for High-Performance Computing (HPC) environments and development systems.\n\n## Features\n\n### Core Functionality\n\nThe tool provides several key features:\n\n1. **Environment Management**: Create, activate, and manage Python virtual environments with configurations stored in `zenv.json`\n2. **Registry**: Track environments globally so they can be activated from any directory\n3. **System Targeting**: Configure environments for specific machines or clusters\n4. **Dependency Management**: Install Python packages with awareness of what's already provided by system modules\n5. **Module Integration**: Load HPC modules required for environment setup\n\n## Installation\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/anoopkcn/zenv/HEAD/install.sh | sh\n```\n\nRun the same command to update already insalled `zenv` version\n\n### Alternative methods of installation\n\n\u003cdetails\u003e\n\u003csummary\u003eManual download of stable release\u003c/summary\u003e\n\n```bash\n# Replace \u003ctag\u003e with last stable release version:\ncurl -LO \"https://github.com/anoopkcn/zenv/releases/download/\u003ctag\u003e/zenv-x86_64-linux-musl-small.tar.gz\"\n\n# Extract the 'zenv' executable and move it somewhere in your 'PATH'\ntar -xvf zenv-x86_64-linux-musl-small.tar.gz\nmv zenv ~/.local/bin/\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eBuild from Source\u003c/summary\u003e\n\n```bash\n# Clone the repository\ngit clone https://github.com/anoopkcn/zenv.git\n\n# Build the project\ncd zenv\nzig build\n\n# Optional: Move executable to ~/.local/bin (assumes ~/.local/bin is in PATH)\nmv zig-out/bin/zenv ~/.local/bin/\n# OR\n# Optional: Add to your PATH\nexport PATH=\"$PATH:path/to/zig-out/bin\"\n```\n\n\u003c/details\u003e\n\nCheck [release](https://github.com/anoopkcn/zenv/releases) for specific versions.\nSupported OS: Linux(`aarch64`, `x86_64`), MacOS(`aarch64`, `x86_64`). _Windows support is not planned_\n\n## Usage\n\n### Initialize and setup an environment\n\n```bash\nzenv init [name] [description]\n# This creates a `zenv.json` configuration file in your project directory\n# You can then modify this json file according to your needs and run:\nzenv setup \u003cname\u003e\n# This will also register the environment to global ZENV_DIR/registry.json\n```\n\n**A minimal example of a `zenv.json` file**:\n\n```json\n{\n  \"base_dir\": \"zenv\",\n  \"test\": {\n    \"target_machines\": [\"*\"],\n    \"description\": \"Basic environment JURECA and any machine\",\n    \"modules\": [\"Stages/2025\", \"StdEnv\", \"Python\"],\n    \"dependency_file\": \"requirements.txt\"\n  }\n}\n```\n\nCheck the [Configuration Reference](#configuration-reference) for full list of key-values. The optional `dependency_file` can be `requirements.txt` OR  `pyproject.toml` file. If you run `zenv init` then it will be automatically populated according to what is found in the project.\n\n### Listing environments\n\nList all environments registered for the current machine:\n\n```bash\nzenv list # for listing envs configured for current computer\n# OR\nzenv list --all # for listing all available envs in the registry\n```\n\nExample output:\n\n```\n- test\n  id      : c3c494547b40f070b4c080f95c707622d84fe749\n  target  : jureca, juwels, *\n  project : /path/to/project/\n  venv    : /path/to/project/zenv/test\n  desc    : Test python environment\n\nFound 1 environment(s) for the current machine ('jrlogin01.jureca').\n```\n\n### Activating environments\n\nActivate an environment by name or ID\n\nExample:\n\n```bash\n# Activate by name\nsource $(zenv activate test)\n\n# Activate by full ID\nsource $(zenv activate c3c494547b40f070b4c080f95c707622d84fe749)\n\n# Activate by partial ID (first 7+ characters)\nsource $(zenv activate c3c4945)\n```\n\n### Direct run without activation\n\nOne could run commands and tools without explicit activation of Environments using `zenv run` command\n\n```bash\nzenv run \u003cname|id\u003e \u003ccommand\u003e\n```\n\nFor example to run a script using python from the environment:\n\n```bash\nzenv run test python my_test_file.py\n```\n\nOr to run a server:\n\n```bash\nzenv run test jupyter notebook\n# OR\nzenv run test mkdocs serve\n```\n\nOR make environment avilable for your editor without activaton:\n\n```bash\n# for vim or neovim\nzenv run test vim\n\n# for vs code\n# zenv run test code -n .\n```\n\n### Registering and Deregistering Environments\n\nA metadata information about the environments are stored at `ZENV_DIR/registry.json`. by default `ZENV_DIR` is `$HOME/.zenv`.\nBut one can set `ZENV_DIR` environment variable as any directory with write permission.\n\nRegister an environment in the global registry:\n\n**This is done automatically when you run `zenv setup \u003cname\u003e`**\n\n```bash\nzenv register \u003cname\u003e\n```\n\nRemove an environment from the registry:\n\n```bash\nzenv deregister \u003cname\u003e     # Remove by name or ID\n```\n\n## Python Management\n\nThe default priority of the Python is as follows:\n\n1. Module-provided Python (if HPC modules are loaded)\n2. Explicitly configured 'fallback_python' from zenv.json (if not null)\n3. zenv-managed pinned Python\n4. System python3\n5. System python\n\nIf you would like to use zenv-managed default Python for the environment, run:\n\n```bash\n# Install a python version if not done already\nzenv python install \u003cversion\u003e\n\n# Pin a specic python version\nzenv python pin \u003cversion\u003e\n\n# usethe pinned version\nzenv setup \u003cname\u003e --python\n```\n\n## Configuration Reference\n\nOne can have multiple environment configurations in the same `zenv.json` file and it supports the following structure:\n\n```json\n{\n  \"base_dir\": \"\u003cbase dirrectory where all envs listed in the config will be stored\u003e\",\n  \"\u003cname\u003e\": {\n    \"target_machines\": [\"\u003cmachine identifier accepts wild card *\u003e\"],\n    \"fallback_python\": \"\u003cpath to python executable OR null\u003e\",\n    \"description\": \"\u003coptional description OR null\u003e\",\n    \"modules\": [\"\u003cmodule1\u003e\", \"\u003cmodule2\u003e\"],\n    \"modules_file\": \"\u003cpath to modules file OR null\u003e\"\n    \"dependency_file\": \"\u003coptional path to requirements_txt OR pyproject_toml OR null\u003e\",\n    \"dependencies\": [\"\u003cpackage name with or without version\u003e\"],\n    \"setup\": {\n      \"commands\": [\"\u003clist of shell commands which is run during setup\u003e\"],\n      \"script\": \"\u003cpath to a shell script which is run during setup\u003e\"\n    },\n    \"activate\": {\n      \"commands\": [\"\u003clist of shell commands which is run during activation\u003e\"],\n      \"script\": \"\u003cpath to a shell script which will be run during activation\u003e\"\n    }\n  },\n  \"\u003canother_name\u003e\": {\n    \"target_machines\": [\"\u003canothor machine identifier\u003e\"]\n  }\n}\n```\n\nOne can run `zenv validate` to validate the config file. If there are errors in the JSON it will try to inform the context of the error.\n\nIn the configuration `target_machines` is required key(If you want, you can disable the validation check using `--no-host`), all other entries are optional. Top-level `base_dir` can be an absolute path or relative one(relative to the `zenv.json` file), if not provided it will create a directory called `zenv` at the project root. One can use wildcards to target specific systems, to mantch any machine use `*` or `any` (`\"target_machines\": [\"*\"]`). The lookup location of the `dependency_file` is the same directory as `zenv.json`.\n\nFor custom scripts, you can use `activate_hook` and `setup_hook` to specify paths to shell scripts that will be copied to the environment's directory and executed during activation or setup. These scripts allow for more complex customization than inline commands. The scripts are copied to the environment directory, making the environment portable and independent of the original script location.\n\nThe key-val `\"modules_file\": \"path/to/file.txt\"` can be specified in an environment to load module names from an external file. The file can contain module names separated by spaces, tabs, commas, or newlines. When specified, any modules listed in the \"modules\" array are ignored.\n\n## Help\n\n```bash\nzenv help\n```\n\nOutput:\n\n```\nUsage: zenv \u003ccommand\u003e [name|id] [options]\n\nManages Python virtual environments based on zenv.json configuration.\n\nCommands:\n  init [name] [desc]         Initializes a new 'zenv.json' in the current directory.\n                             Creates a 'test' environment if 'name' is not provided.\n                             Use to start defining your environments[z].\n\n  setup \u003cname\u003e               Creates and configures the virtual environment for '\u003cname\u003e'.\n                             Builds the environment in '\u003cbase_dir\u003e/\u003cname\u003e' as per 'zenv.json'.\n                             This is the primary command to build an environment.\n\n  activate \u003cname|id|.\u003e       Outputs the activation script path for an environment.\n                             To use: source $(zenv activate \u003cname|id|.\u003e)\n\n  run \u003cname|id|.\u003e \u003ccommand\u003e  Executes a \u003ccommand\u003e within the specified isolated environment.\n                             Does NOT require manual activation of the environment.\n\n  cd \u003cname|id|.\u003e             Outputs the project directory path for an environment.\n                             To use: cd $(zenv cd \u003cname|id|.\u003e)\n\n  list                       Lists registered environments accessible on this machine.\n\n  list --all                 Lists all registered environments.\n\n  register \u003cname\u003e            Adds the environment '\u003cname\u003e' (from current 'zenv.json') to the\n                             global registry[a], making it accessible from any location.\n\n  deregister \u003cname|id|.\u003e     Removes an environment from the global registry.\n                             The virtual environment files are NOT deleted.\n\n  rename \u003cold|id\u003e \u003cnew\u003e      Renames an environment from 'old' to 'new'.\n                             Updates the registry, renames the virtual environment directory,\n                             updates generated scripts, and updates any associated Jupyter kernels.\n                             Preserves all configuration and metadata.\n\n  validate [config]          Validates the configuration file. If no arguent provided it\n                             will validate the 'zenv.json' file in the current directory.\n                             Reports errors with line numbers and field names if found.\n\n  log \u003cname|id|.\u003e            Displays the setup log file for the specified environment.\n\n  alias \u003csubcommand\u003e         Manages environment aliases for easier access:\n    create \u003calias\u003e \u003cenv\u003e     Creates an alias for an environment.\n    remove \u003calias\u003e           Removes an existing alias.\n    list                     Lists all defined aliases.\n    show \u003calias\u003e             Shows what environment an alias points to.\n\n  jupyter \u003csubcommand\u003e       Manages Jupyter kernels for environments:\n    create \u003cenv_name\u003e        Creates a Jupyter kernel for the specified environment.\n    remove \u003cenv_name\u003e        Removes the Jupyter kernel for the specified environment.\n    list                     Lists all zenv-managed Jupyter kernels.\n    check                    Checks if Jupyter is installed and available.\n\n  python \u003csubcommand\u003e        (Experimantal feature) Manages Python installations:\n    install \u003cversion\u003e        Downloads and installs a specific Python version for zenv.\n    pin \u003cversion\u003e            Sets \u003cversion\u003e as the pinned Python for zenv to prioritize.\n    list                     Shows Python versions installed and managed by zenv.\n\n  version, -v, --version     Prints the installed zenv version.\n\n  help, --help               Shows this help message.\n\nOptions for 'zenv setup \u003cname\u003e':\n  --init                     Creates and populates 'zenv.json' file before 'zenv setup'.\n                             Convenient for creating and setting up in one step.\n\n  --dev                      Installs the current directory's project in editable mode.\n                             Equivalent to 'pip install --editable .' command.\n\n  --uv                       Uses 'uv' instead of 'pip' for package operations.\n                             Ensure 'uv' is installed and accessible.\n\n  --no-host                  Bypasses hostname validation during setup.\n                             Equivalent to \"target_machines\": [\"*\"] in zenv.json.\n                             Use if an environment should be set up regardless of the machine.\n\n  --python                   Use the zenv-pinned Python for creating environment.\n                             Ignores the default Python priority[b] list.\n\n  --force                    Forces reinstallation of all dependencies.\n                             Useful if dependencies from loaded modules cause conflicts.\n\n  --no-cache                 Disables the package cache when installing dependencies.\n                             Ensures fresh package downloads for each installation.\n\n  --jupyter                  Creates a Jupyter kernel for the environment after setup.\n                             Equivalent to running 'zenv jupyter create \u003cname\u003e' after setup.\n\n[z] Configuration (zenv.json):\n  The 'zenv.json' file is a JSON formatted file that defines your environments.\n  Each top-level key is an environment name. \"base_dir\": \"path/to/venvs\" is a special\n  top-level key specifying the storage location for virtual environments.\n  Paths can be absolute (e.g., /path/to/venvs) or relative to the 'zenv.json' location.\n\n[a] Registry (ZENV_DIR/registry.json):\n  A global JSON file (path in ZENV_DIR environment variable, typically $HOME/.zenv)\n  that tracks registered environments. This allows 'zenv' commands to manage\n  these environments from any directory. Environments are added via 'zenv setup'\n  or 'zenv register'.\n\n[b] Python Priority List (for 'zenv setup' without '--python' flag):\n  zenv attempts to find a Python interpreter in the following order:\n  1. HPC module-provided Python (if HPC environment modules are loaded).\n  2. Path explicitly specified by the 'fallback_python' key in zenv.json.\n  3. zenv-pinned Python (set via 'zenv python use \u003cversion\u003e').\n  4. System Python.\n  Use 'zenv setup \u003cname\u003e --python' to use only the pinned version.\n\n[.] Dot Notation:\n  Use '.' as the environment identifier to automatically select an environment\n  from the current directory. This works when you're in a directory containing\n  a zenv.json file and have registered environments for that directory.\n```\n\n## Issues\n\nIf you encounter any bugs open an Issue. To use the debug logging feature, users can set the `ZENV_DEBUG` environment variable:\n\nExample:\n\n```bash\nZENV_DEBUG=1 zenv setup \u003cname\u003e\n```\n\n## License\n\n[MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanoopkcn%2Fzenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanoopkcn%2Fzenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanoopkcn%2Fzenv/lists"}