{"id":17412732,"url":"https://github.com/rtmigo/vien_py","last_synced_at":"2025-04-15T20:24:12.854Z","repository":{"id":62587425,"uuid":"344647832","full_name":"rtmigo/vien_py","owner":"rtmigo","description":"💻 Command-line tool for managing Python virtual environments","archived":false,"fork":false,"pushed_at":"2022-03-21T02:58:37.000Z","size":685,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T03:06:43.515Z","etag":null,"topics":["interpreter","python","shortcuts","venv","virtual-environment","virtual-environments","virtualenv","virtualenv-manager","virtualenvs","virtualenvwrapper"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/vien/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rtmigo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-05T00:29:48.000Z","updated_at":"2024-05-03T15:39:07.000Z","dependencies_parsed_at":"2022-11-03T22:38:08.533Z","dependency_job_id":null,"html_url":"https://github.com/rtmigo/vien_py","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtmigo%2Fvien_py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtmigo%2Fvien_py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtmigo%2Fvien_py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtmigo%2Fvien_py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rtmigo","download_url":"https://codeload.github.com/rtmigo/vien_py/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249146524,"owners_count":21220157,"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","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":["interpreter","python","shortcuts","venv","virtual-environment","virtual-environments","virtualenv","virtualenv-manager","virtualenvs","virtualenvwrapper"],"created_at":"2024-10-17T00:07:52.319Z","updated_at":"2025-04-15T20:24:12.820Z","avatar_url":"https://github.com/rtmigo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PyPI version shields.io](https://img.shields.io/pypi/v/vien.svg)](https://pypi.python.org/pypi/vien/)\n[![Generic badge](https://img.shields.io/badge/Python-3.7+-blue.svg)](#)\n[![Generic badge](https://img.shields.io/badge/OS-Linux%20|%20macOS-blue.svg)](#)\n[![Downloads](https://pepy.tech/badge/vien/month)](https://pepy.tech/project/vien)\n\n# [vien](https://github.com/rtmigo/vien_py#readme)\n\n**VIEN** is a command-line tool for managing\n[Python Virtual Environments](https://docs.python.org/3/library/venv.html).\n\nIt provides one-line shortcuts for:\n\n- creating and deleting environments\n- running commands inside environments\n- switching between environments in bash shell\n\n-----\n\nSwitching between projects should be simple. Creating environments for the\nprojects should be simple too.\n\nIdeally it's a short command that I would type even half asleep.\n\nSomething like\n\n``` bash\n$ vien create \n$ vien shell\n```\n\nNot like\n\n``` bash\n$ python3 -m venv ./where/to/put/this/.venv\n$ source /i/lost/that/.venv/bin/activate\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eReady-made solutions did not help.\u003c/summary\u003e\u003cbr/\u003e\n\n- [pipenv](https://pipenv.pypa.io/) kind of solved the problem, but brought new\n  challenges unrelated to virtual environments\n- [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/) name is easier\n  to copy-paste than to type. And its commands are too\n\n\u003c/details\u003e\n\nSo there is the `vien`. A tool for a half asleep developer.\n\n# Install\n\n`vien` requires Python 3.7+ on Linux or macOS.\n\n\n\u003cdetails\u003e\n  \u003csummary\u003eGet a working Python ≥3.7, pip3 and venv.\u003c/summary\u003e\u003cbr/\u003e\n\n@ Ubuntu\n\n``` bash\n$ sudo apt install -y python3 python3-pip python3-venv\n```\n\n@ macOS\n\n``` bash\n$ brew install python3\n```\n\nCheck it works\n\n``` bash\n$ python3 --version             # python shows its version\n$ python3 -m venv --help        # venv shows help message\n$ pip3 install --upgrade pip    # pip upgrades itself\n```\n\n----\n\u003c/details\u003e\n\nThen:\n\n``` bash\n$ pip3 install vien\n```\n\nMake sure it installed:\n\n``` bash\n$ vien      # shows help\n```\n\nUpgrade it later:\n\n``` bash\n$ pip3 install vien --upgrade\n```\n\n# Use\n\n### Example: interactive shell\n\n``` bash\n$ cd /path/to/myProject\n$ vien create\n$ vien shell\n```\n\n### Example: running commands\n\n``` bash\n$ cd /path/to/myProject\n$ vien create\n$ vien run pip install --upgrade pip\n$ vien run pip install requests lxml\n$ vien call main.py\n```\n\n# \"create\" command\n\n`vien create` сreates a virtual environment that will correspond the\n**project directory**. Subsequent calls to `vien`\nwith the same project directory will use the same virtual environment.\n\n``` bash\n$ cd /abc/myProject\n$ vien create \n```\n\nBy default, the current **working directory** is assumed to be the\n**project directory**. You can override this with `-p` argument.\n\n``` bash\n$ vien -p /abc/myProject create \n```\n\nThe `-p` argument works with all commands, not only `create`.\n\n``` bash\n$ cd /other/working/dir\n$ vien -p /abc/myProject create\n$ vien -p /abc/myProject shell\n```\n\n### \"create\": choose the Python version\n\nIf you have several versions of Python installed, then virtual environments can\nhelp you switch not only between dependencies, but also between interpreters.\n\n``` bash\n$ cd /abc/my_old_project\n$ vien run python --version  # 3.7  \n\n$ cd /abc/my_newer_project\n$ vien run python --version  # 3.9 \n```\n\nA project directory can be bound to only one specific interpreter.\n\nTo indicate which interpreter to use with the project, provide an argument\npointing the executable.\n\n``` bash\n$ vien create /usr/local/opt/python@3.8/bin/python3\n```\n\nIn many cases, a shorter command will also work. If the needed interpreter can\nbe executed in the shell as `python3.8`, you can try\n\n``` bash\n$ vien create python3.8\n```\n\nWhen `create` is called with no argument, `vien` will use the Python interpreter\nthat is running `vien` itself. For example, if you used Python 3.9\nto `pip install vien`, then it is the Python 3.9 runs `vien`, and this Python\n3.9 will be used in the virtual environment.\n\n# \"shell\" command\n\n`vien shell` starts interactive bash session in the virtual environment.\n\n``` bash\t\n$ cd /path/to/myProject\n$ vien shell\n\n(myProject)$ _\n```\n\nNow you are inside the virtual environment.\n\n``` bash\t\n(myProject)$ which python3             # now we are using separate copy of Python\n(myProject)$ echo $PATH                # everything is slightly different\n\n(myProject)$ pip3 install requests     # installs packages into virtual environment\n(myProject)$ python3 use_requests.py   # runs inside the virtual environment\n```\n\nGet out of the virtual environment:\n\n``` bash\n(myProject)$ exit\n\n$ _\n```\n\nNow you're back.\n\nWith shell pipes, you can specify what the shell should execute right in the\ncommand line.\n\n``` bash\n$ echo 'which python3 \u0026\u0026 echo $PATH' | vien shell\n```\n\n# \"run\" command\n\n`vien run COMMAND` runs a shell command in the virtual environment.\n\n``` bash \t\t\n$ cd /path/to/myProject\n$ vien run python3 use_requests.py arg1 arg2  # runs script in virtual environment\n$ vien run pip3 install requests              # installs packages into virtual environment\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eis an equivalent to\u003c/summary\u003e\u003cbr/\u003e\n\n``` bash \t\t\n$ cd /path/to/myProject\n\n$ source /path/to/the/venv/bin/activate\n$ python3 use_requests.py arg1 arg2\n$ /path/to/the/venv/bin/deactivate\n\n$ source /path/to/the/venv/bin/activate\n$ pip3 install requests\n$ /path/to/the/venv/bin/deactivate\n```\n\n\u003c/details\u003e\n\ncall                            | run\n--------------------------------|-----------------------------------------------\nRuns only `python file.py` or `python -m module` | Can run any shell command: `pip3`, `cd`, etc.\nStarts one python process       | Starts two processes: parent shell and child python\n\n# \"call\" command\n\n`vien call PYFILE` executes a `.py` script in the virtual environment.\n\n### \"call\": running file as a file\n\n``` bash\n$ cd /abc/myProject\n$ vien call pkg/module.py\n  \n# runs [python pkg/module.py]\n```\n\n### \"call\": running file as a module\n\nIf the `.py` file name is preceded by the `-m` argument, we will run it with\n`python -m MODULE`. Running in this manner often simplifies importing other\nmodules from the program.\n\n``` bash\n$ cd /abc/myProject\n$ vien call -m /abc/myProject/pkg/sub/module.py\n\n# runs [python -m pkg.sub.module]\n# project dir: /abc/myProject\n# working dir: /abc/myProject\n```\n\n- `module.py` must be located somewhere inside the `/abc/myProject`\n- parent subdirectories such as `pkg` and `sub` must be importable, i.e. must\n  contain\n  `__init__.py`\n- the project directory will be inserted into `$PYTHONPATH`, making\n  `pkg.sub.module` resolvable from `/abc/myProject` to a file\n\nThe project directory can be specified not only by the working directory, but\nalso by the `-p` argument.\n\nThe `call` command only accepts `.py` files, no module names.\n\n``` bash\n# ERROR: there is no file named pkg.module\n$ vien call -m pkg.module \n```\n\n### \"call\": passing arguments to Python and to the program\n\nArguments following the `call` command are passed to the python executable.\n\n``` bash \t\t\n$ vien call -B -OO -m package/main.py arg1 arg2  \n\n# runs [python -B -OO -m package.main arg1 arg2]\n```\n\n### \"call\": project directory\n\nThe optional `-p` argument can be specified before the `call` word. It allows\nyou to set the project directory **relative** to the parent directory of the\n**file** being run.\n\n``` bash\n$ cd /far/away\n$ vien -p /abc/myProject call -m /abc/myProject/pkg/sub/module.py\n\n# runs [python -m pkg.sub.module]\n# project dir: /abc/myProject\n# working dir: /far/away\n```\n\n``` bash\n$ cd /far/away\n$ vien -p ../.. call -m /abc/myProject/pkg/sub/module.py\n\n# runs [python -m pkg.sub.module]\n# project dir: /abc/myProject  (/abc/myProject/pkg/sub/../..)\n# working dir: /far/away\n```\n\n``` bash\n$ cd /abc/myProject/pkg\n$ vien -p ../.. call -m sub/module.py\n\n# runs [python -m pkg.sub.module]\n# project dir: /abc/myProject  (/abc/myProject/pkg/sub/../..)\n# working dir: /abc/myProject/pkg\n```\n\n# \"delete\" command\n\n`vien delete` deletes the virtual environment.\n\n``` bash\n$ cd /path/to/myProject\n$ vien delete \n```\n\n# \"recreate\" command\n\n`vien recreate` old and creates new virtual environment.\n\nIf you decided to start from scratch:\n\n``` bash\n$ cd /path/to/myProject\n$ vien recreate \n```\n\nIf you decided to change the Python version:\n\n``` bash\n$ cd /path/to/myProject\n$ vien recreate /usr/local/opt/python@3.10/bin/python3\n```\n\n# --project-dir, -p\n\nThis option must appear after `vien`, but before the command.\n\n``` bash\nvien -p /abc/myProject create ...\nvien -p /abc/myProject run ...\nvien -p /abc/myProject shell ...\n```\n\nIf `--project-dir` is specified, it is the project directory.\n\nIf `--project-dir` is not specified, then all commands assume that the current\nworking directory is the project directory.\n\nThe next two calls use the same project directory and the same virtual\nenvironment. However, the working directory is different.\n\n``` bash\ncd /abc/myProject\nvien run python3 /abc/myProject/main.py\n```\n\n``` bash\ncd /any/where\nvien -p /abc/myProject run python3 /abc/myProject/main.py\n```\n\nIf `--project-dir` is specified as a **relative path**, its interpretation\ndepends on the command.\n\n- For the `call` command, this is a path relative to the parent directory of\n  the `.py` file being run\n- For other commands, this is a path relative to the current working directory\n\n# Virtual environments location\n\nBy default, `vien` places virtual environments in the `$HOME/.vien` directory.\n\n|project dir|virtual environment dir|\n|-----|----|\n|`/abc/thisProject`|`$HOME/.vien/thisProject_venv`|\n|`/abc/otherProject`|`$HOME/.vien/otherProject_venv`|\n|`/moved/to/otherProject`|`$HOME/.vien/otherProject_venv`|\n\nOnly the local name of the project directory matters.\n\nIf you're not happy with the default, you can set the environment\nvariable `VIENDIR`:\n\n``` bash\n$ export VIENDIR=\"/x/y/z\"\n```\n\nSo for the project `aaa` the virtual environment will be located\nin `/x/y/z/aaa_venv`.\n\nThe `_venv` suffix tells the utility that this directory can be safely removed.\n\n# Shebang\n\nOn POSIX systems, you can make a `.py` file executable, with `vien` executing it\ninside a virtual environment.\n\nInsert the shebang line to the top of the file you want to run. The value of the\nshebang depends on the location of the file relative to the project directory.\n\nFile                            | Shebang line\n--------------------------------|--------------------------------------\n`myProject/runme.py`            | `#!/usr/bin/env vien -p . call -m`\n`myProject/pkg/runme.py`        | `#!/usr/bin/env vien -p .. call -m`\n`myProject/pkg/subpkg/runme.py` | `#!/usr/bin/env vien -p ../.. call -m`\n\nAfter inserting the shebang, make the file executable:\n\n``` bash\n$ chmod +x runme.py  \n```\n\nNow you can run the `runme.py` directly from command line. This will use the\nvirtual environment associated with the `myProject`. The working directory can\nbe anything.\n\n``` bash\n# runs the runme.py in virtual environment for myProject\n\n$ cd anywhere/somewhere\n$ /abc/myProject/pkg/main.py   \n```\n\n# Shell prompt\n\nBy default the `vien shell` adds a prefix to\nthe [`$PS1`](https://wiki.archlinux.org/index.php/Bash/Prompt_customization)\nbash prompt.\n\n``` bash\nuser@host$ cd /abc/myProject\nuser@host$ vien shell\n\n(myProject)user@host$ _\n```\n\nSo you can see, which virtual environment you're using.\n\nIf you customized your `PS1`, it may not work as expected.\n\n``` bash\npersonalized:prompt\u003e cd /abc/myProject\npersonalized:prompt\u003e vien shell\n\n(myProject)user@host$ _\n```\n\nIt can be fixed by providing `PS1` variable to `vien` like that:\n\n``` bash\npersonalized:prompt\u003e cd /abc/myProject\npersonalized:prompt\u003e PS1=$PS1 vien shell\n\n(myProject)personalized:prompt\u003e _\n```\n\nTo avoid doing this each time, `export` your `PS1` to make it available for\nsubprocesses.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frtmigo%2Fvien_py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frtmigo%2Fvien_py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frtmigo%2Fvien_py/lists"}