venvs is a tool for configuring, in a single file, a set of virtualenvs, which packages to install into each, and any binaries to make globally available from within.
It is a thin layer on top of uv, adding a declarative configuration format.
Installation
uv tool install venvs
uv must be installed and on your PATH.
Configuration
Create a file at ~/.local/share/virtualenvs/virtualenvs.toml (or wherever $WORKON_HOME points). Here’s an example:
[virtualenv.development]
install = [
"pudb",
"twisted",
]
link = ["trial"]
[virtualenv.app]
install = ["flask"]
python = "python3.12"
link = ["flask:flask-app"]
[virtualenv.tools]
install = ["ipython"]
link-module = ["IPython:ipy"]Running venvs converge will create each virtualenv, install the specified packages, and symlink the named binaries into ~/.local/bin/.
Config Reference
Each [virtualenv.<name>] section supports:
- install
List of packages to install (supports $ENV_VAR and ~/ expansion).
- requirements
List of requirements files to install from.
- python
Python interpreter to use (default: python3).
- install-bundle
List of bundle names to include (see below).
- link
List of binaries to symlink into the link directory. Use "source:target" to rename, e.g. "black:black3.12".
- link-module
List of modules to make available as wrapper scripts that run python -m <module>. Use "module:name" to rename.
- post-commands
List of commands (as arrays) to run after converging, e.g. [["touch", "/tmp/done"]].
Bundles
Bundles are reusable package groups:
[bundle]
dev = ["pytest", "ruff", "mypy"]
[virtualenv.myproject]
install = ["mypackage"]
install-bundle = ["dev"]Usage
venvs converge
Converge the configured set of virtualenvs:
$ venvs converge
Specific virtualenvs can be targeted:
$ venvs converge myproject tools
Options:
- --fail-fast
Stop on the first failure (default: continue and report errors at the end).
- --link-dir <path>
Directory to symlink binaries into (default: ~/.local/bin).
- --root <path>
Root directory for virtualenvs (default: platform-specific, or $WORKON_HOME).
Converge is idempotent – if the configuration and Python version haven’t changed and the virtualenv is healthy, it is skipped. Virtualenvs that are no longer in the configuration are automatically removed along with their symlinks. Broken virtualenvs (e.g. from a deleted Python installation) are automatically recreated.
Virtualenvs are converged in parallel.
venvs find
Find virtualenv paths:
$ venvs find # print the root directory $ venvs find name myproject # print the virtualenv path $ venvs find name myproject python # print path to a binary
Releasing
Releases are managed via cargo-release:
$ cargo release 2026.5.1
1 maintainer
Metadata
1 maintainer
Release files for venvs 2026.5.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| venvs-2026.5.1.tar.gz | 28.4 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| venvs-2026.5.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details |
| venvs-2026.5.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details |
| venvs-2026.5.1-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.whl | Python 3 | none | Linux glibc 2.5+ x86-64 | Details |
| venvs-2026.5.1-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details |
| venvs-2026.5.1-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details |
Total release size: 4.2 MB
Release files / venvs-2026.5.1.tar.gz
| Download URL | venvs-2026.5.1.tar.gz |
|---|---|
| Size | 28.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
37030b6cbb343598a1b3e9e97ab03c06f53a9216e8ca13edc4996ae5d56bd226
|
|
BLAKE2b-256 checksum How to use checksums |
8bd2bfb3b2fb563082f3df1201355342b67cc3cee59a29d336910faf63a6af4b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 3, 2026.
Transparency logRelease files / venvs-2026.5.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | venvs-2026.5.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 833.2 kB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
cb7b7ec67b655a44097eae58e7a894b223f062ce899273647bc3d043d6b36b01
|
|
BLAKE2b-256 checksum How to use checksums |
f49c8a1affdc4f471c05a5a17ae75fec2bc7c72580b2a91ebfbf829e10bc1210
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 3, 2026.
Transparency logRelease files / venvs-2026.5.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | venvs-2026.5.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 839.0 kB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
af72b5c395ddae240566d53932370bbd6e8af25584cf764be26ff5b5e2701ba4
|
|
BLAKE2b-256 checksum How to use checksums |
b851f89053676216118a9b3ba38eff0216a76fc14627804523b9fbdd48309353
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 3, 2026.
Transparency logRelease files / venvs-2026.5.1-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.whl
| Download URL | venvs-2026.5.1-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.whl |
|---|---|
| Size | 899.5 kB |
| Tags | Linux glibc 2.5+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
861d8052c9ae67d94e5edba3d5a1818be85911f3f6169b6352f73b55d8365b68
|
|
BLAKE2b-256 checksum How to use checksums |
59bfb8024b91215618dceb715a3935f0224dfceadc588b3cc94c91bd3a757e1d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 3, 2026.
Transparency logRelease files / venvs-2026.5.1-py3-none-macosx_11_0_arm64.whl
| Download URL | venvs-2026.5.1-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 768.9 kB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
837a62c7a1a48fa4622a933fc39ee9707e4aee2e4a2ec01a027a85b02f912072
|
|
BLAKE2b-256 checksum How to use checksums |
54dc867b8c0a38be6c8e8344e012cbc3f42c589c3f5192e9056945e580dd7c1a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 3, 2026.
Transparency logRelease files / venvs-2026.5.1-py3-none-macosx_10_12_x86_64.whl
| Download URL | venvs-2026.5.1-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 799.9 kB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
07812bbfa93755db11eacc20d8a59bd99a8ab2f0556876b7e5545aff34dc2737
|
|
BLAKE2b-256 checksum How to use checksums |
549b953ab42c7e7f199c39906c4df105ebfc543d085fd9cf8eb85d046a09b633
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 3, 2026.
Transparency log
