You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+60-52Lines changed: 60 additions & 52 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,28 +4,31 @@
4
4
5
5
## Overview
6
6
`venv-cli` is a CLI tool to help create and manage virtual python environments.
7
-
It uses `pip` and `python -m venv` underneath, and so only requires core python. This alleviates the bootstrapping problem of needing to install a python package using your system `python` and `pip` before you are able to create virtual environments.
7
+
It is built on `pip` and `python -m venv`, and so only requires packages that are already part of the core python installation; no third-party python packages required. This alleviates the bootstrapping problem of needing to install a python package using your system `python` and `pip` before you are able to create virtual environments.
8
8
9
9
You also don't need `conda`, `pyenv`, `pythonz` etc. to manage your python versions. Just make sure the correct version of python is installed on your system, then reference that specific version when creating the virtual environment, and everything just works. No shims, no path hacks, just the official `python` build.
10
10
11
11
## Installation
12
12
13
-
Clone this repository, then run the `install.sh` script from your favourite shell:
13
+
Clone this repository, then run the `install.sh` script:
14
14
```console
15
-
$ bash install.sh
15
+
$ ./install.sh
16
16
```
17
17
This will install the `venv` source file, along with an uninstall script, in `/usr/local/share/venv/`, and add a line in the appropriate shell `rc`-file (e.g. `~/.bashrc`) sourcing the `venv` source script.
18
18
19
-
This makes the `venv` command avaiable in your terminal. To check if it works, restart the terminal and run
19
+
The default shell is `bash`. To install for a different shell, specify the shell name, e.g.
20
+
```console
21
+
$ ./install.sh zsh
22
+
```
23
+
24
+
The installation makes the `venv` command available in your terminal. To check if it works, restart the terminal and run
20
25
```console
21
26
$ venv --version
22
27
venv-cli 1.0.0
23
28
```
24
29
25
-
The install script also adds command completions for the invoked shell.
26
-
27
30
# Uninstall
28
-
To uninstall `venv` and remove all files, run the uninstall script at `/usr/local/share/venv/`:
31
+
To uninstall `venv` and remove all files, run the uninstall script placed at `/usr/local/share/venv/`:
29
32
```console
30
33
$ bash /usr/local/share/venv/uninstall.sh
31
34
```
@@ -54,14 +57,13 @@ $ venv create 3.9 venv-name
54
57
55
58
If you don't have the specific version of python installed yet, you can get it by running
56
59
```console
57
-
$ sudo apt install python<version>-venv
60
+
$ sudo apt install python<version>
58
61
```
59
62
e.g.
60
63
```console
61
-
$ sudo apt install python3.10-venv
64
+
$ sudo apt install python3.10
62
65
```
63
-
64
-
The `-venv` part is necessary to be able to use this system python to create virtual environments.
66
+
(or in the case of Debian-based distributions, like Ubuntu, `sudo apt install python3.10-venv`. The `-venv` part is necessary to be able to use the system python to create virtual environments.)
65
67
66
68
## Activating and deactivating the virtual environment
67
69
To activate the virtual environment, place yourself _in the folder containing_ the `.venv` folder, then run
@@ -74,64 +76,62 @@ To deactivate it again, run
74
76
$ venv deactivate
75
77
```
76
78
77
-
## Install packages/requirements
78
-
The proper way to install packages in the virtual environment is to add them to a `requirements.txt` file and then install from that:
79
-
79
+
## Install/uninstall packages and requirements
80
+
To install a single package, simply run
80
81
```console
81
-
$ echo"pandas ~= 1.5">> requirements.txt
82
+
$ venv install <package>
83
+
```
82
84
83
-
$ venv install requirements.txt
85
+
This will install the `<package>` in the current environment. However, it does more than that.
86
+
A main design philosophy of `venv-cli` is to always keep the current environment in a reproducible state. For this reason, `venv-cli` aims to always keep a requirements file up to date with that state.
84
87
85
-
Installing requirements from requirements.txt
86
-
Collecting pandas~=1.5
87
-
Using cached pandas-1.5.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (12.1 MB)
88
-
Collecting python-dateutil>=2.8.1
89
-
Using cached python_dateutil-2.8.2-py2.py3-none-any.whl (247 kB)
90
-
Collecting numpy>=1.21.0
91
-
Using cached numpy-1.25.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (17.6 MB)
92
-
Collecting pytz>=2020.1
93
-
Using cached pytz-2023.3-py2.py3-none-any.whl (502 kB)
94
-
Collecting six>=1.5
95
-
Using cached six-1.16.0-py2.py3-none-any.whl (11 kB)
This means that when running `venv install <package>`, the package is first added (or appended) to a `requirements.txt` file in the current folder, and then the command `venv install -r requirements.txt` is run, which clears the entire environment and reinstalls it from scratch using the requirements specified in `requirements.txt`.
99
89
100
-
In fact, if you don't specify the file name, `venv` will assume that you want to install from `requirements.txt`, so
101
-
```console
102
-
$ venv install
90
+
Unlike `pip install <package>`, which leaves no trace, this ensures that the `requirements.txt` keeps a record of the packages that have been manually installed.
103
91
104
-
$ venv install requirements.txt
92
+
In the same spirit, `venv uninstall <package>` first removes the package from `requirements.txt`, then runs `venv install -r requirements.txt` to reinstall the environment from scratch. Unlike `pip uninstall <package>`, this ensures that the uninstall does not leave any "orphaned" packages in the current environment (packages that were installed as secondary dependencies, but are no longer needed since the primary dependency has been uninstalled).
93
+
94
+
### Requirements files
95
+
To specify a different requirements file to install to/uninstall from, use `-r <requirements>` :
96
+
```console
97
+
$ venv install numpy 'pandas >= 2.0' -r core.txt
98
+
```
99
+
This will add `numpy` and `pandas >= 2.0` as requirements in `core.txt`, then install from that file. Similarly,
100
+
```console
101
+
$ venv uninstall pandas -r core.txt
105
102
```
106
-
are equivalent.
103
+
will remove the `pandas >= 2.0` requirement from `core.txt` again, then reinstall the environment using the updated `core.txt`.
107
104
108
-
The installed packages are then _locked_ into the corresponding `.lock`-file, e.g. running `venv install dev-requirements.txt` will lock those installed packages into `dev-requirements.lock`[^1].
105
+
### Lock files
106
+
When installing or uninstalling packages, the resulting environment is _locked_ into a corresponding `.lock`-file, e.g. running `venv install -r requirements.txt` will lock the installed packages into `requirements.lock`[^1].
109
107
110
-
Installing packages this way makes sure that they are tracked, since installing them with `pip install` will keep no record of which packages have been installed in the environment, making it difficult to reproduce later on.
108
+
This file is useful if a reproducible install is needed, e.g. when deploying a project to a different machine, or when running a colleagues project. Where `requrements.txt` is used to specify the packages and version your project _needs_ (and nothing more), installing from `requirements.lock` makes sure that you get the exact version of every package.
111
109
112
-
### Development packages
113
-
If you have both production and development package requirements, keep them in separate requirements-files, e.g. `requirements.txt` for production and `dev-requirements.txt` for development. An example of these could be:
110
+
### Additional requirements
111
+
If you have both production and development package requirements, keep them in separate requirements-files, e.g. `requirements.txt` for production requirements and `test.txt` for requirements needed when running tests. An example of these could be:
114
112
```bash
115
113
# requirements.txt
116
114
numpy
117
115
pandas ~= 1.5
118
116
119
117
120
-
#dev-requirements.txt
118
+
#test.txt
121
119
-r requirements.txt
122
-
jupyter
123
-
matplotlib
120
+
pytest
121
+
pytest-cov
124
122
```
125
123
126
-
The `-r requirements.txt` will make sure that installing development requirements also install production requirements.
124
+
You can then use either
125
+
```console
126
+
$ venv install -r requirements.txt
127
+
```
127
128
128
-
## Reproducing environment
129
-
To install a reproducible environment, you need to install from a `.lock`-file, since those have all versions of all requirements locked[^1]:
129
+
To install production requirements only, or
130
130
```console
131
-
$ venv install requirements.lock
131
+
$ venv install -r test.txt
132
132
```
133
133
134
-
This will first clear the environment of any installed packages, then install the packages and versions specified in `requirements.lock`.
134
+
to install both production and test requirements. The `-r requirements.txt` in `test.txt` is what makes sure that installing test requirements also installs the requirements from `requirements.txt`.
135
135
136
136
## Clearing the environment
137
137
If you want to manually clear the environment, you can run
@@ -149,19 +149,27 @@ $ venv clear
149
149
$ venv install requirements.txt
150
150
```
151
151
152
-
## Contributing
152
+
## Deleting the environment
153
+
To completely delete the virtual environment and everything in it, run
154
+
```console
155
+
$ venv delete
156
+
```
153
157
154
-
As this is meant to be a lightweight tool providing simple, QoL improvements to working with `pip` and `python -m venv`, we will not be adding a lot of big, additional features.
158
+
(this will not delete any requirement or .lock-files). This will ask for confirmation before deleting the virtual environment. To give immediate confirmation, pass the `-y` flag:
159
+
```console
160
+
$ venv delete -y
161
+
```
155
162
156
-
That said, pull requests are welcome. For bigger changes, please open an issue first to discuss what you would like to change.
163
+
## Contributing
164
+
Before creating a pull request, please open an issue first to discuss what you would like to change.
157
165
158
-
To contribute, clone the repo and create a branch, create a virtual environment (preferably using `venv-cli`) and install `dev-requirements.txt`. When you are done with your changes, run the test suite with
166
+
To contribute, clone the repo and create a branch, create a virtual environment and install `dev-requirements.txt`. When you are done with your changes, run the test suite with
159
167
```console
160
168
$ pytest .
161
169
```
162
170
then create a pull request for the `develop` branch.
163
171
164
-
Every subcommand has its own test file `tests/test_venv_<command>.py` Please make sure to add/update tests as appropriate.
172
+
Every (public) subcommand has its own test file `tests/test_venv_<command>.py` Please make sure to add/update tests as appropriate.
165
173
166
174
### Git Flow
167
175
This project follows the [Git Flow](https://nvie.com/posts/a-successful-git-branching-model/) branching model. The default development branch is accordingly named `develop`, and the branch `main` is reserved for tagged releases and hotfixes. Other branches should be named according to their purpose:
0 commit comments