Metadata-Version: 2.4
Name: venvstudio
Version: 1.6.109
Summary: Lightweight Python Virtual Environment Manager with modern GUI
Author-email: Bayram Kotan <bayramkotan@outlook.com>
License: LGPL-3.0-or-later
Project-URL: Homepage, https://github.com/bayramkotan/VenvStudio
Project-URL: Repository, https://github.com/bayramkotan/VenvStudio
Project-URL: Documentation, https://github.com/bayramkotan/VenvStudio#readme
Project-URL: Bug Tracker, https://github.com/bayramkotan/VenvStudio/issues
Project-URL: Release Notes, https://github.com/bayramkotan/VenvStudio/releases
Keywords: python,virtual-environment,venv,pip,uv,package-manager,gui,desktop,qt,pyside6
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6>=6.5.0
Requires-Dist: packaging
Provides-Extra: dev
Requires-Dist: pyinstaller>=6.0; extra == "dev"
Requires-Dist: Pillow; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: fast
Requires-Dist: uv; extra == "fast"
Dynamic: license-file

<div align="center">

# 🐍 VenvStudio

**Lightweight Python Virtual Environment Manager**  
Create, manage, and launch your Python environments — all from a modern GUI

![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-f9e2af?style=for-the-badge)

</div>

---

## 📦 Install

```bash
pip install venvstudio
venvstudio
```

**🐧 On Linux, pip may refuse to install.** Most current distributions mark the
system Python as *externally managed* (PEP 668), so a plain `pip install` stops
with `error: externally-managed-environment`. Two ways around it:

```bash
# Isolated — recommended, no system packages touched
pipx install venvstudio

# Into the system Python — needs the override flag
sudo pip install venvstudio --break-system-packages --no-cache-dir -U
```

The same flag applies when upgrading a system-wide install later on.

Or download the standalone binary — **no Python required:**

| Platform | File | Notes |
|:--------:|:-----|:------|
| 🪟 **Windows** | [`VenvStudio.exe`](https://github.com/bayramkotan/VenvStudio/releases/latest) | Portable — just run |
| 🐧 **Linux** | [`VenvStudio-x86_64.AppImage`](https://github.com/bayramkotan/VenvStudio/releases/latest) | `chmod +x` then run |
| 🍎 **macOS** | [`VenvStudio-macOS`](https://github.com/bayramkotan/VenvStudio/releases/latest) | Apple Silicon + Rosetta 2 |

---

## ✨ Features

### 🗂️ Environment Management
- **8 environment types** — Python venv, uv, Poetry, Conda (micromamba), pipx, Hatch, PDM, Pixi
- Create, rename, clone, delete virtual environments with a modern GUI
- **Type** column — see each env's package manager at a glance (🐍 venv, ⚡ uv, 📜 Poetry, 🦎 Conda, 📦 pipx, 🏗️ Hatch, 📦 PDM, 🌊 Pixi)
- **Runtime** column — actual Python version detected from each environment's binary
- Auto-detect existing environments on disk at startup
- Per-environment cache — instant load, no subprocess delays
- Set a **Default Environment** that opens automatically on launch
- Open terminal with environment pre-activated (cmd, PowerShell, pwsh, bash, zsh, fish...)
- Export as `requirements.txt`, `requirements-frozen.txt` (SHA-256 hashes), JSON, `Dockerfile`, `docker-compose.yml`, `pyproject.toml`, `environment.yml`

### 🔧 Supported Environment Types

| Icon | Type | Backend | Description |
|:----:|:-----|:--------|:------------|
| 🐍 | **Python venv** | `python -m venv` | Standard virtual environment with pip |
| ⚡ | **uv** | `uv venv` | Rust-powered — 10–100× faster than pip |
| 📜 | **Poetry** | `poetry new` | Dependency management with lock file |
| 📦 | **pipx** | `pipx install` | Isolated CLI applications |
| 🦎 | **Conda** | micromamba | conda-forge — R, napari, ParaView, JupyterHub, MinIO and 25,000+ packages |
| 🏗️ | **Hatch** | `hatch new` | Modern Python project manager by PyPA with pyproject.toml |
| 📦 | **PDM** | `pdm init` | PEP 582 / pyproject.toml based package manager |
| 🌊 | **Pixi** | `pixi init` | conda-forge + PyPI, blazing fast Rust-powered environment |

### 🧩 Conflict Manager

VenvStudio checks packages against a curated compatibility list **before**
installing them — every install path (Catalog, Presets, Manual Install,
Install Launcher) goes through the same check, so nothing slips through.

- **218 curated rules** — packages with known Python-version limits,
  environment restrictions, or that need a native/conda build instead
  of a plain pip wheel
- **Live PyPI fallback** — for packages not on the curated list,
  VenvStudio checks PyPI directly for a matching wheel before installing
- **Reads wheel tags properly** — a `cp310-abi3` wheel is the stable ABI:
  one file that serves Python 3.10 and every version after it, and a
  `py3-none` wheel is pure Python wherever it was built. Both are read
  correctly, so PyQt6 and astropy are no longer refused on a new Python
  that they support
- **Tells wheel from source** — packages that cap their wheels at an older
  Python but still ship an sdist (vpython, fiona, kivy) are reported as
  *installs, but compiles* rather than as unavailable
- Click any package for a **detail panel**: plain-English explanation,
  the exact install command for your environment type, and one-click
  actions — 🚀 Install, 🌱 Create New Environment, 🔄 Try Alternative
  (swap in a known-good replacement, e.g. PyQt5 → PySide6), 📚 Open in
  Learn
- **Scan Environment** — check every package already installed, not
  just new ones
- **Export** — save the full compatibility table as CSV or JSON

**When an install fails, it says why.** pip answers `No matching
distribution found` both when the name is wrong and when the name is right
but nothing in the release fits this Python. VenvStudio asks PyPI about each
name separately and names which of the two it is — with a *did you mean* for
a real typo, and the Python versions that do have a file for the other case.

### 📦 Package Management
- **Installed** tab — filter, select, uninstall, export, import packages
- **Catalog** tab — 535 curated packages across 39 categories with PyPI & Docs links
- **Presets** tab — one-click install bundles (Data Science, Web API, Django, Flask, ML, NLP, CV, Testing...)
- **Manual Install** tab — paste package names or version specs (`numpy==1.24`, `pandas>=2.0`)
- pip or **uv** backend (uv is 10–100× faster)

### 📁 Projects

- **One table for every project**, whichever tool built it — uv, Poetry, PDM, Hatch and Pixi side by side
- **Scan for Projects** finds existing ones on disk; **New Project** scaffolds one with the tool you pick
- **Source and environment sized separately**, so a 900 MB project turns out to be 20 KB of code and the rest environment
- **Command Reference** shows the exact commands behind every button — `poetry install`, `pdm add <package>`
- **Add Package** goes through the project's own tool, so `pyproject.toml` is updated rather than bypassed

### 🚀 Quick Launch
- Sidebar shows installed apps for the active environment
- **26 one-click launchers** — see full list below
- **Install Launcher** (File menu) — pick any app, VenvStudio finds a compatible environment automatically or offers to create one
- **Conda applications** — R, napari, Glue, Veusz, OpenRefine, ParaView, JupyterHub and MinIO, installed from conda-forge into the environment
- **External applications** — RStudio, jamovi, JASP, DBeaver and Ollama are in no conda channel, so Tools → External Apps launches them if they are on the system and opens the vendor's download page if not
- **Jupyter Working Directory** — configurable (Home / Env Folder / Custom Path)
- **Create Desktop Shortcut** for any app
- Instant sync between sidebar dropdown, environment table, and package panel

### 🐍 Python Management
- Auto-detect all system Python installations
- Add custom Python paths
- Set **User Default** or **System Default** Python (PATH management with optional admin elevation)
- Download standalone Python builds from [python-build-standalone](https://github.com/astral-sh/python-build-standalone)

### ⚙️ Settings & Customization
- 🌙 13 themes (8 dark + 5 light, Catppuccin-based)
- 3-level font system (Headings / UI & Menus / Details)
- 🌍 11 languages: EN, TR, DE, ES, RU, JA, AR, FR, PT, ZH, KO
- **Conda mirrors** — reorderable list with automatic failover; a `Skip Mirror` button jumps to the next one mid-install instead of waiting out a slow server
- **pipx interpreter** — pin which Python your CLI apps get installed with, useful when the newest release is ahead of the tools you need
- Custom venv base directory
- Custom terminal, catalog categories, and packages
- CLI/TUI Tools: **Starship** (preset preview, inline config editor, test terminal), **Oh My Posh**, **Nerd Fonts**
- Auto-check for updates on startup

---

## 🧰 Tools

- **🗺️ Code Map** — reads the codebase and reports what is defined twice, which mixin methods are shadowed, which constants are twins and which definitions nothing calls
- **📓 Running Jupyter Servers** — lists the notebook servers actually running, wherever they were started from, with port, working directory, kernel count and last activity; stops them properly rather than killing them
- **📊 External Apps** — applications that are in no conda channel: launches them if present, opens the download page if not

---

## 🚀 Supported Launchers

*Launch any of these tools directly from VenvStudio — if installed in the active environment, it appears in the sidebar automatically.*

### 📓 Python Launchers (venv, uv, Hatch, PDM, Poetry)

| | Tool | Description | Category | Website |
|:---:|:-----|:-----------|:--------:|:-------:|
| ![Jupyter](https://img.shields.io/badge/-F37626?style=flat-square&logo=jupyter&logoColor=white) | **JupyterLab** | Next-gen interactive development environment for notebooks | 📓 Notebooks | [jupyter.org](https://jupyter.org/) |
| ![Jupyter](https://img.shields.io/badge/-F37626?style=flat-square&logo=jupyter&logoColor=white) | **Jupyter Notebook** | Classic notebook interface for interactive computing | 📓 Notebooks | [jupyter.org](https://jupyter.org/) |
| ![Streamlit](https://img.shields.io/badge/-FF4B4B?style=flat-square&logo=streamlit&logoColor=white) | **Streamlit** | Build data apps in minutes with pure Python | 🌐 Web Apps | [streamlit.io](https://streamlit.io/) |
| ![Gradio](https://img.shields.io/badge/-F97316?style=flat-square&logo=gradio&logoColor=white) | **Gradio** | Build and share ML demos and web apps | 🌐 Web Apps | [gradio.app](https://gradio.app/) |
| ![Dash](https://img.shields.io/badge/-3F4F75?style=flat-square&logo=plotly&logoColor=white) | **Plotly Dash** | Analytical web applications with Python | 🌐 Web Apps | [dash.plotly.com](https://dash.plotly.com/) |
| ![Panel](https://img.shields.io/badge/-4E8BBE?style=flat-square) | **Panel** | High-level app and dashboarding framework | 🌐 Web Apps | [panel.holoviz.org](https://panel.holoviz.org/) |
| ![Voilà](https://img.shields.io/badge/-5B4B8A?style=flat-square) | **Voilà** | Turn Jupyter notebooks into standalone web apps | 🌐 Web Apps | [voila.readthedocs.io](https://voila.readthedocs.io/) |
| ![FastAPI](https://img.shields.io/badge/-009688?style=flat-square&logo=fastapi&logoColor=white) | **FastAPI** | Modern, fast web framework for building APIs | ⚡ API | [fastapi.tiangolo.com](https://fastapi.tiangolo.com/) |
| ![TensorBoard](https://img.shields.io/badge/-FF6F00?style=flat-square&logo=tensorflow&logoColor=white) | **TensorBoard** | Visualization toolkit for machine learning experiments | 📊 ML Ops | [tensorflow.org/tensorboard](https://www.tensorflow.org/tensorboard) |
| ![MLflow](https://img.shields.io/badge/-0194E2?style=flat-square&logo=mlflow&logoColor=white) | **MLflow** | Platform for the complete ML lifecycle | 📊 ML Ops | [mlflow.org](https://mlflow.org/) |
| ![Spyder](https://img.shields.io/badge/-838485?style=flat-square&logo=spyderide&logoColor=white) | **Spyder IDE** | Scientific Python development environment | 🔬 IDE | [spyder-ide.org](https://www.spyder-ide.org/) |
| ![Orange](https://img.shields.io/badge/-E6812C?style=flat-square) | **Orange Data Mining** | Visual programming for data analysis and ML | 🔬 Data Science | [orangedatamining.com](https://orangedatamining.com/) |
| ![Datasette](https://img.shields.io/badge/-4A8B6E?style=flat-square) | **Datasette** | Explore and publish data with instant JSON API | 🗄️ Data | [datasette.io](https://datasette.io/) |
| ![Marimo](https://img.shields.io/badge/-8B5CF6?style=flat-square) | **Marimo** | Reactive notebook — no hidden state, runs as an app | 📓 Notebooks | [marimo.io](https://marimo.io/) |
| ![Quarto](https://img.shields.io/badge/-75AADB?style=flat-square&logo=quarto&logoColor=white) | **Quarto** | Publish documents, reports and dashboards | 📄 Publishing | [quarto.org](https://quarto.org/) |
| ![IPython](https://img.shields.io/badge/-3776AB?style=flat-square&logo=python&logoColor=white) | **IPython** | Enhanced interactive Python shell | 🐍 Shell | [ipython.org](https://ipython.org/) |
| ![Chainlit](https://img.shields.io/badge/-000000?style=flat-square) | **Chainlit** | Build conversational AI / LLM chat apps | 🗣️ LLM & GenAI | [chainlit.io](https://chainlit.io/) |
| ![Shiny](https://img.shields.io/badge/-4E9BCD?style=flat-square) | **Shiny** | Python web apps for data science, R-inspired | 🌐 Web Apps | [shiny.posit.co](https://shiny.posit.co/py/) |
| ![NiceGUI](https://img.shields.io/badge/-5898D4?style=flat-square) | **NiceGUI** | Python-only web UIs, no HTML/CSS/JS needed | 🌐 Web Apps | [nicegui.io](https://nicegui.io/) |
| ![Bokeh](https://img.shields.io/badge/-2E7D9E?style=flat-square) | **Bokeh** | Interactive visualization for modern browsers | 📊 ML Ops | [bokeh.org](https://bokeh.org/) |
| ![Prefect](https://img.shields.io/badge/-070E10?style=flat-square) | **Prefect** | Workflow orchestration — runs the Prefect server UI | 🔀 Orchestration | [prefect.io](https://www.prefect.io/) |
| ![Evidently](https://img.shields.io/badge/-ED0400?style=flat-square) | **Evidently** | Data and model monitoring — drift, quality, performance | 📉 Monitoring | [evidentlyai.com](https://www.evidentlyai.com/) |
| ![Jupyter](https://img.shields.io/badge/-F37626?style=flat-square&logo=jupyter&logoColor=white) | **Notebook (classic)** | The classic notebook interface on modern Jupyter Server | 📓 Notebooks | [jupyter.org](https://jupyter.org/) |

### 🛠️ Conda Applications

*Installed from conda-forge into the environment itself.*

| Tool | Description | conda-forge package |
|:-----|:-----------|:--------------------|
| **R Console** | R statistical computing language | `r-base` |
| **napari** | n-dimensional image viewer | `napari` |
| **Glue** | Linked-view exploration of related datasets | `glueviz` |
| **Veusz** | Scientific plotting and graphing | `veusz` |
| **OpenRefine** | Clean and transform messy data | `openrefine` |
| **ParaView** | Large-scale scientific visualisation | `paraview` |
| **JupyterHub** | Multi-user Jupyter server | `jupyterhub` |
| **MinIO** | S3-compatible object storage server | `minio-server` |

### 🌐 External Applications

*In no conda channel — Tools → External Apps launches them if present, or
opens the download page. Checked against conda-forge, bioconda, defaults, r
and anaconda.*

RStudio · jamovi · JASP · DBeaver · Ollama

---

## 🚀 Quick Start

### From PyPI

```bash
pip install venvstudio
venvstudio
```

### From Source

```bash
git clone https://github.com/bayramkotan/VenvStudio.git
cd VenvStudio
pip install PySide6
python main.py
```

### Linux — System Dependencies

Before running VenvStudio on Linux, install the required Qt/XCB libraries:

**Debian / Ubuntu / Pardus / Linux Mint:**
```bash
sudo apt update
sudo apt install libxcb-xinerama0 libxcb-cursor0 libxcb-icccm4 libxcb-image0 \
                 libxcb-keysyms1 libxcb-render-util0 libxcb-shape0 libxkbcommon-x11-0
```

**Arch Linux / CachyOS / Manjaro:**
```bash
sudo pacman -S xcb-util-cursor xcb-util-icccm xcb-util-image \
               xcb-util-keysyms xcb-util-renderutil libxkbcommon-x11
```

**Fedora / RHEL / CentOS:**
```bash
sudo dnf install libxcb xcb-util-cursor xcb-util-icccm xcb-util-image \
                 xcb-util-keysyms xcb-util-renderutil libxkbcommon-x11
```

**openSUSE Leap / Tumbleweed:**
```bash
sudo zypper install libxcb-cursor0 libxcb-icccm4 libxcb-image0 \
                    libxcb-keysyms1 libxcb-render-util0 libxkbcommon-x11-0 libgthread-2_0-0
```

> **Note:** If the AppImage fails with `Could not load the Qt platform plugin "xcb"`, installing these packages will fix it.

### CLI

VenvStudio is a GUI first, but the core actions work headless too — handy over SSH,
in scripts, or when you just want one quick thing done.

Installing with pip gives you two names for the same tool: **`vs`** to type and
**`venvstudio`** to read. Use whichever you like.

| Short | Full | What it does |
|:------|:-----|:-------------|
| `vs` | `venvstudio` | Launch the GUI |
| `vs list` | `venvstudio list` | List every detected environment |
| `vs create NAME` | `venvstudio create NAME` | Create a venv environment |
| `vs create NAME -t uv` | `venvstudio create NAME -t uv` | Create a uv environment |
| `vs create NAME -t poetry` | `venvstudio create NAME -t poetry` | Create a Poetry environment |
| `vs create NAME -t conda` | `venvstudio create NAME -t conda` | Create a Conda environment |
| `vs create NAME -t hatch` | `venvstudio create NAME -t hatch` | Create a Hatch environment |
| `vs create NAME -t pdm` | `venvstudio create NAME -t pdm` | Create a PDM environment |
| `vs create NAME -t pixi` | `venvstudio create NAME -t pixi` | Create a Pixi environment |
| `vs delete NAME` | `venvstudio delete NAME` | Delete an environment (asks first) |
| `vs delete NAME -y` | `venvstudio delete NAME -y` | Delete without the confirmation prompt |
| `vs packages ENV` | `venvstudio packages ENV` | List packages installed in ENV |
| `vs install ENV PKG...` | `venvstudio install ENV PKG...` | Install one or more packages into ENV |
| `vs uninstall ENV PKG...` | `venvstudio uninstall ENV PKG...` | Uninstall packages from ENV |
| `vs preset list` | `venvstudio preset list` | List every preset with its packages |
| `vs preset install NAME ENV` | `venvstudio preset install NAME ENV` | Install a whole preset into ENV |
| `vs preset remove NAME ENV` | `venvstudio preset remove NAME ENV` | Uninstall a preset's packages from ENV |
| `vs update` | `venvstudio update` | Update VenvStudio itself to the latest release |
| `vs update -c` | `venvstudio update -c` | Only check — print the available version, change nothing |
| `vs update -y` | `venvstudio update -y` | Update without the confirmation prompt |
| `vs -V` | `venvstudio -V` | Show version (also: `version`) |
| `vs -h` | `venvstudio -h` | Show help |

```bash
vs                        # short and sweet
venvstudio list           # or spell it out
vs install myenv requests httpx
```

On Windows, `venvstudio-gui` starts the GUI without a console window.

---

## 📤 Export and Import

Export your environment in multiple formats from the **Export ▾** dropdown:

| Format | File(s) | Use Case |
|--------|---------|----------|
| 📄 requirements.txt | `requirements.txt` | Standard pip |
| 🔒 requirements-frozen.txt | `requirements-frozen.txt` | Reproducible install with SHA-256 hashes |
| 📋 JSON | `packages.json` | Machine-readable package list |
| 🐳 Dockerfile | `Dockerfile` + `requirements.txt` | Docker container |
| 🐳 docker-compose.yml | 3 files | Docker Compose |
| 📦 pyproject.toml | `pyproject.toml` | Modern Python packaging |
| 🐍 environment.yml | `environment.yml` | Conda compatibility |
| 📋 Clipboard | — | Quick copy-paste |

**Import** does the reverse — pick a `requirements.txt`-style file and
VenvStudio installs everything in it into the current environment,
using the right command for that environment's type (`pip install -r`,
`uv pip install -r`, `poetry install`, `conda install --file`).

---

## ⬇️ Python Downloader

Download standalone Python builds straight from VenvStudio — no system install,
no admin rights needed.

**Five sources, tried in order until one answers:**

| Source | What it serves |
|:-------|:---------------|
| **Astral** *(default)* | [python-build-standalone](https://github.com/astral-sh/python-build-standalone) via GitHub Releases — the same builds `uv` uses |
| **GitHub Releases** | Same builds, fetched directly |
| **python.org** | Official CPython source tarballs |
| **SourceForge** | Mirror — often faster in some regions |
| **Custom URL** | Point it anywhere you like |

The default chain is Astral → GitHub → python.org: if one is unreachable or slow,
VenvStudio moves to the next on its own. Pick your preferred source in
**Settings → Python**.

**Install target:**

- **User Install** — no admin required, stored in VenvStudio config
- **System Install** — Windows (`C:\Program Files`), Linux (`/opt/python`), macOS (`/usr/local/python`)

---

## 🏗️ Build from Source

```bash
pip install pyinstaller PySide6 Pillow
python build.py
```

---

## 📝 License

[LGPL-3.0](https://github.com/bayramkotan/VenvStudio/blob/main/LICENSE)

---

<div align="center">

**Made with ❤️ by [Bayram Kotan](https://github.com/bayramkotan)**

[GitHub](https://github.com/bayramkotan/VenvStudio) · [Releases](https://github.com/bayramkotan/VenvStudio/releases) · [Issues](https://github.com/bayramkotan/VenvStudio/issues) · [Screenshots](https://github.com/bayramkotan/VenvStudio#-screenshots)

⭐ **If VenvStudio helps you, give it a star!** ⭐

</div>
