{"id":31956761,"url":"https://github.com/murapadev/venvswitch","last_synced_at":"2025-10-14T14:53:14.495Z","repository":{"id":318229795,"uuid":"1057467309","full_name":"murapadev/venvswitch","owner":"murapadev","description":"Smart Python virtual environment switching for Zsh","archived":false,"fork":false,"pushed_at":"2025-10-05T22:33:41.000Z","size":22,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-06T00:21:15.547Z","etag":null,"topics":["oh-my-zsh","oh-my-zsh-plugin","python-virtual-environment","virtual-environment-manager"],"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/murapadev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-15T19:08:19.000Z","updated_at":"2025-10-05T22:33:44.000Z","dependencies_parsed_at":"2025-10-06T00:21:22.363Z","dependency_job_id":"828fd18b-4f3b-47ec-9b92-786868d9ef0a","html_url":"https://github.com/murapadev/venvswitch","commit_stats":null,"previous_names":["murapadev/venvswitch"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/murapadev/venvswitch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/murapadev%2Fvenvswitch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/murapadev%2Fvenvswitch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/murapadev%2Fvenvswitch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/murapadev%2Fvenvswitch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/murapadev","download_url":"https://codeload.github.com/murapadev/venvswitch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/murapadev%2Fvenvswitch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279019141,"owners_count":26086685,"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-14T02:00:06.444Z","response_time":60,"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":["oh-my-zsh","oh-my-zsh-plugin","python-virtual-environment","virtual-environment-manager"],"created_at":"2025-10-14T14:53:05.950Z","updated_at":"2025-10-14T14:53:14.488Z","avatar_url":"https://github.com/murapadev.png","language":"Shell","readme":"# venvswitch 🐍\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Zsh](https://img.shields.io/badge/shell-zsh-blue.svg)](https://zsh.org/)\n[![Oh My Zsh](https://img.shields.io/badge/plugin-Oh%20My%20Zsh-red.svg)](https://ohmyz.sh/)\n\n\u003e **Smart Python virtual environment switching for Zsh**\n\nA powerful Zsh plugin that automatically detects and switches between Python virtual environments based on project files. Unlike other tools, venvswitch creates **local virtual environments** in your project directories, keeping your development environment clean and organized.\n\n## ✨ Features\n\n- 🔄 **Automatic Switching**: Detects and switches virtual environments when entering directories\n- 📁 **Local Environments**: Creates virtual environments directly in project folders\n- 🛠️ **Multi-tool Support**: Works with `virtualenv`, `pipenv`, `poetry`, and `conda`\n- ⚡ **Performance Optimized**: Intelligent caching system for fast directory scanning\n- 🎛️ **Highly Configurable**: Extensive customization options via environment variables\n- 🛡️ **Robust Error Handling**: Comprehensive validation and error recovery\n- 🎨 **Beautiful Output**: Colorized messages with customizable formatting\n- 📊 **Smart Detection**: Recognizes project types from multiple indicator files\n\n## 📋 Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Commands](#commands)\n- [Examples](#examples)\n- [Troubleshooting](#troubleshooting)\n- [Advanced Usage](#advanced-usage)\n- [Compatibility](#compatibility)\n- [Contributing](#contributing)\n- [License](#license)\n\n## 🚀 Installation\n\n### Prerequisites\n\n- **Zsh** (v5.0 or later)\n- **Oh My Zsh** framework\n- **Python** (3.6+ recommended)\n- At least one Python environment tool: `virtualenv`, `pipenv`, `poetry`, or `conda`\n\n### Install Steps\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone https://github.com/murapadev/venvswitch.git ~/.oh-my-zsh/custom/plugins/venvswitch\n   ```\n\n2. **Add to your `~/.zshrc`:**\n\n   ```bash\n   plugins=(... venvswitch)\n   ```\n\n3. **Restart your terminal:**\n\n   ```bash\n   source ~/.zshrc\n   ```\n\n4. **Verify installation:**\n   ```bash\n   venvswitch_config\n   ```\n\n## 🎯 Quick Start\n\n```bash\n# Create a new Python project\nmkdir my-awesome-project\ncd my-awesome-project\n\n# Create and activate a virtual environment\nmkvenv\n\n# You're now in an isolated Python environment!\n# The .venv directory is created locally in your project\n\n# Install packages\npip install requests flask\n\n# Work on your project...\npython app.py\n\n# When done, clean up\nrmvenv\n```\n\n## 📖 Usage\n\n### Automatic Detection\n\nvenvswitch automatically detects Python projects by looking for these files:\n\n| Tool           | Indicator Files                            | Priority   |\n| -------------- | ------------------------------------------ | ---------- |\n| **Poetry**     | `poetry.lock`, `pyproject.toml`            | 🔝 Highest |\n| **Pipenv**     | `Pipfile`, `Pipfile.lock`                  | 🔝 High    |\n| **Conda**      | `environment.yml`, `conda-environment.yml` | 🔝 Medium  |\n| **Virtualenv** | `.venv/`, `requirements.txt`, `setup.py`   | 🔝 Low     |\n\n### Manual Control\n\n```bash\n# Enable automatic switching\nenable_venvswitch\n\n# Disable automatic switching\ndisable_venvswitch\n\n# Check current status\nvenvswitch_config\n\n# Clear scan cache\nvenvswitch_clear_cache\n```\n\n## ⚙️ Configuration\n\nCustomize behavior with environment variables in your `~/.zshrc`:\n\n### Core Settings\n\n```bash\n# Virtual environment directory name\nexport VENVSWITCH_VENV_DIR=\".venv\"          # Default: \".venv\"\n\n# Scanning behavior\nexport VENVSWITCH_MAX_DEPTH=\"10\"            # Default: 10 levels up\nexport VENVSWITCH_IGNORE_DIRS=\"node_modules .git .svn .cache\"\n\n# Performance\nexport VENVSWITCH_CACHE_ENABLED=\"true\"      # Default: true\nexport VENVSWITCH_CACHE_TTL=\"30\"            # Cache TTL in seconds\n\n# Tool preferences (order matters!)\nexport VENVSWITCH_PREFERRED_TOOLS=\"poetry pipenv conda virtualenv\"\n```\n\n### Advanced Settings\n\n```bash\n# Python version\nexport VENVSWITCH_DEFAULT_PYTHON=\"python3.9\"\n\n# Project detection\nexport VENVSWITCH_PROJECT_FILES=\"Pipfile poetry.lock environment.yml requirements.txt setup.py pyproject.toml\"\n\n# Output control\nexport VENVSWITCH_SILENT=\"\"                 # Set to suppress messages\nexport VENVSWITCH_MESSAGE_FORMAT=\"🔄 Switching to %venv_type: %venv_name (%py_version)\"\n\n# Installation behavior\nexport VENVSWITCH_PIPINSTALL=\"FULL\"         # \"FULL\" for pip install . vs -e .\nexport VENVSWITCH_DEFAULT_REQUIREMENTS=\"$HOME/.default-requirements.txt\"\n```\n\n## 🛠️ Commands\n\n| Command                  | Description                                       |\n| ------------------------ | ------------------------------------------------- |\n| `mkvenv [options]`       | Create virtual environment in current directory   |\n| `rmvenv`                 | Remove virtual environment from current directory |\n| `enable_venvswitch`      | Enable automatic environment switching            |\n| `disable_venvswitch`     | Disable automatic environment switching           |\n| `venvswitch_config`      | Show current configuration                        |\n| `venvswitch_clear_cache` | Clear the scan cache                              |\n\n## 💡 Examples\n\n### Basic Virtual Environment\n\n```bash\nmkdir django-project\ncd django-project\n\n# Create virtual environment with Python 3.9\nmkvenv --python=python3.9\n\n# Install Django\npip install django\n\n# Create Django project\ndjango-admin startproject myproject .\n\n# The .venv directory is created locally\nls -la\n# drwxr-xr-x .venv/\n# -rw-r--r-- manage.py\n# drwxr-xr-x myproject/\n```\n\n### Poetry Project\n\n```bash\n# Initialize Poetry project\npoetry init\n\n# Install dependencies and create environment\nmkvenv\n\n# Poetry environment is created and activated\npoetry env list\n# /path/to/project/.venv (Activated)\n```\n\n### Pipenv Project\n\n```bash\n# Create Pipenv project\npipenv install flask requests\n\n# Setup environment\nmkvenv\n\n# Pipenv environment is activated\npipenv --venv\n# /path/to/project/.venv\n```\n\n### Conda Environment\n\n```bash\n# Create environment.yml\ncat \u003e environment.yml \u003c\u003c EOF\nname: data-science\ndependencies:\n  - python=3.9\n  - numpy\n  - pandas\n  - jupyter\nEOF\n\n# Create conda environment\nmkvenv\n\n# Environment is activated\nconda info --envs\n# data-science *  /path/to/project/.venv\n```\n\n### Custom Configuration\n\n```bash\n# Use 'venv' instead of '.venv'\nexport VENVSWITCH_VENV_DIR=\"venv\"\n\n# Prefer conda over virtualenv\nexport VENVSWITCH_PREFERRED_TOOLS=\"poetry pipenv conda virtualenv\"\n\n# Custom activation message\nexport VENVSWITCH_MESSAGE_FORMAT=\"🐍 Activated %venv_name (%py_version)\"\n\n# Reload configuration\nsource ~/.zshrc\n```\n\n## 🔧 Troubleshooting\n\n### Plugin Not Loading\n\n```bash\n# Check if plugin is in your plugins list\ngrep \"venvswitch\" ~/.zshrc\n\n# Verify Oh My Zsh is working\nomz --version\n\n# Check for syntax errors\nzsh -n ~/.oh-my-zsh/custom/plugins/venvswitch/venvswitch.plugin.zsh\n```\n\n### Environment Not Detected\n\n```bash\n# Clear cache and retry\nvenvswitch_clear_cache\n\n# Check configuration\nvenvswitch_config\n\n# Verify project files exist\nls -la | grep -E \"(Pipfile|poetry\\.lock|environment\\.yml|\\.venv)\"\n\n# Check if directory is ignored\necho $VENVSWITCH_IGNORE_DIRS\n```\n\n### Performance Issues\n\n```bash\n# Reduce scan depth\nexport VENVSWITCH_MAX_DEPTH=\"3\"\n\n# Add more ignore patterns\nexport VENVSWITCH_IGNORE_DIRS=\".git node_modules .cache __pycache__\"\n\n# Disable caching if needed\nexport VENVSWITCH_CACHE_ENABLED=\"false\"\n```\n\n### Permission Errors\n\n```bash\n# Check directory permissions\nls -ld /path/to/project\n\n# Fix permissions if needed\nchmod 755 /path/to/project\n\n# For conda, ensure proper initialization\nconda init zsh\n```\n\n### Conflicts with Other Tools\n\n```bash\n# Check for conflicting plugins\nplugins=(... venvswitch)  # Ensure venvswitch is loaded last\n\n# Disable other virtualenv plugins temporarily\n# plugins=(... )  # Remove conflicting plugins\n```\n\n### Debug Mode\n\n```bash\n# Enable verbose output\nexport VENVSWITCH_SILENT=\"\"\n\n# Check what the plugin detects\ncd /path/to/project\nvenvswitch_config\n\n# Monitor cache usage\nvenvswitch_clear_cache\n# Navigate directories and check cache status\n```\n\n## 🚀 Advanced Usage\n\n### Custom Project Types\n\nExtend project detection for custom workflows:\n\n```bash\n# Add custom project files\nexport VENVSWITCH_PROJECT_FILES=\"$VENVSWITCH_PROJECT_FILES custom-project.json\"\n\n# Create custom detection logic in your .zshrc\nfunction my_custom_detector() {\n    if [[ -f \"custom-project.json\" ]]; then\n        # Custom environment setup\n        export CUSTOM_VAR=\"value\"\n    fi\n}\n\n# Hook into directory changes\nadd-zsh-hook chpwd my_custom_detector\n```\n\n### Integration with Other Tools\n\n#### With direnv\n\n```bash\n# .envrc file\nexport DATABASE_URL=\"postgresql://localhost/myproject\"\nexport SECRET_KEY=\"your-secret-key\"\n\n# venvswitch handles Python, direnv handles other env vars\n```\n\n#### With fzf\n\n```bash\n# Fuzzy search Python environments\nfunction fzf-venv() {\n    local venv_dir=$(find . -name \".venv\" -type d 2\u003e/dev/null | fzf)\n    if [[ -n \"$venv_dir\" ]]; then\n        source \"$venv_dir/bin/activate\"\n    fi\n}\n```\n\n#### With tmux\n\n```bash\n# Automatically activate environment in new tmux panes\nif [[ -n \"$TMUX\" ]]; then\n    # tmux-specific configuration\n    export VENVSWITCH_AUTO_ACTIVATE=\"true\"\nfi\n```\n\n### CI/CD Integration\n\n```bash\n# For GitHub Actions or similar\nexport VENVSWITCH_VENV_DIR=\"venv\"\nexport VENVSWITCH_CACHE_ENABLED=\"false\"\n\n# Create environment for CI\nmkvenv --python=python3.9\npip install -r requirements.txt\n```\n\n## 🔌 Compatibility\n\n### Supported Platforms\n\n- **Linux**: ✅ Fully supported\n- **macOS**: ✅ Fully supported\n- **Windows**: ⚠️ Requires WSL or similar\n\n### Supported Tools\n\n| Tool           | Version     | Status |\n| -------------- | ----------- | ------ |\n| **virtualenv** | 16.0+       | ✅     |\n| **pipenv**     | 2018.11.26+ | ✅     |\n| **poetry**     | 1.0+        | ✅     |\n| **conda**      | 4.6+        | ✅     |\n| **mamba**      | 0.15+       | ✅     |\n\n### Zsh Compatibility\n\n- **Zsh 5.0+**: ✅ Full support\n- **Zsh 4.x**: ⚠️ Limited support (upgrade recommended)\n- **Oh My Zsh**: ✅ Required\n- **Prezto**: ❌ Not supported\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Fork and clone the repository\ngit clone https://github.com/yourusername/venvswitch.git\ncd venvswitch\n\n# Create development environment\nmkvenv --python=python3.9\n\n# Install development dependencies\npip install -r requirements-dev.txt\n\n# Run tests\n./test/run_tests.sh\n\n# Check code style\n./scripts/lint.sh\n```\n\n### Reporting Issues\n\n1. Check existing issues on GitHub\n2. Use the issue template\n3. Include:\n   - Your Zsh version (`zsh --version`)\n   - Oh My Zsh version (`omz --version`)\n   - Python version and environment tool versions\n   - Steps to reproduce\n   - Expected vs actual behavior\n\n### Pull Requests\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Update documentation\n6. Submit PR with clear description\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 📋 Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a complete list of changes and version history.\n\n## 🙏 Acknowledgments\n\nThis project builds upon the foundational concepts from the excellent [zsh-autoswitch-virtualenv](https://github.com/MichaelAquilina/zsh-autoswitch-virtualenv) project by Michael Aquilina. While venvswitch shares the core idea of automatic virtual environment switching, it has been completely rewritten with significant enhancements and improvements.\n\nSpecial thanks to:\n- **Michael Aquilina** for the original zsh-autoswitch-virtualenv concept\n- The **Oh My Zsh** community for the framework\n- The **Python** and **Zsh** communities for their amazing tools\n\nBuilt with ❤️ for developers who want clean, organized Python environments.\n\n\n## 📞 Support\n\n- 📖 [Documentation](https://github.com/murapadev/venvswitch/wiki)\n- 🐛 [Issue Tracker](https://github.com/murapadev/venvswitch/issues)\n- 💬 [Discussions](https://github.com/murapadev/venvswitch/discussions)\n\n---\n\n**Made with ❤️ by [murapadev](https://github.com/murapadev)**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmurapadev%2Fvenvswitch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmurapadev%2Fvenvswitch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmurapadev%2Fvenvswitch/lists"}