docs: add mise to Environment Management intro

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Vinta Chen
2026-10-16 18:37:53 +08:00
co-authored by Claude
parent cd7b3e4f62
commit 7f5fee1997
@@ -5,6 +5,7 @@ How to choose:
- Python versions and virtual environments from one tool: uv
- A Python API for creating environments, or plugins: virtualenv
- Switching the `python` command between versions, and nothing more: pyenv
- One version manager for Python and other languages' tools: mise
uv [manages Python versions](https://docs.astral.sh/uv/) as well as packages. When a command needs a Python you don't have, uv [downloads it for you](https://docs.astral.sh/uv/guides/install-python/), so you don't need Python installed to get started. A project's virtual environment lives in a `.venv` folder [inside the project, where editors can find it](https://docs.astral.sh/uv/concepts/projects/layout/#the-project-environment); keep it out of version control. Outside a project, `uv venv --python <version>` [creates an environment](https://docs.astral.sh/uv/pip/environments/) with that version, and downloads it if needed.
@@ -12,4 +13,6 @@ virtualenv [creates isolated Python environments](https://virtualenv.pypa.io/en/
pyenv does one job: it [lets you switch between multiple versions of Python](https://github.com/pyenv/pyenv), and leaves virtual environments [to you or its pyenv-virtualenv plugin](https://github.com/pyenv/pyenv#in-contrast-with-pythonbrew-and-pythonz-pyenv-does-not). Install it with the [automatic installer](https://github.com/pyenv/pyenv#1-automatic-installer-recommended) or, on macOS, Homebrew, then [set up your shell](https://github.com/pyenv/pyenv#b-set-up-your-shell-environment-for-pyenv) for it. [Choose the version](https://github.com/pyenv/pyenv#switch-between-python-versions) with `pyenv shell` for the session, `pyenv local` for a directory, or `pyenv global` for your user account. [Most versions are built from source](https://github.com/pyenv/pyenv#install-additional-python-versions) as you install them, so install Python's build dependencies first. pyenv [doesn't work on Windows](https://github.com/pyenv/pyenv#windows) outside the Windows Subsystem for Linux, so on Windows, use uv, which [supports Windows](https://docs.astral.sh/uv/).
Whichever tools you combine, name each project's Python in a `.python-version` file. `pyenv local` [writes that file](https://github.com/pyenv/pyenv#understanding-python-version-selection), and so does `uv python pin`, whose docs [recommend a plain version number](https://docs.astral.sh/uv/concepts/python-versions/#python-version-files) there so other tools can read it. virtualenv [uses the version pyenv selected](https://virtualenv.pypa.io/en/latest/how-to/usage.html#using-version-managers-pyenv-mise-asdf) with no extra configuration. Don't install packages into the Python that came with your operating system, which [often manages its packages itself](https://docs.astral.sh/uv/pip/environments/); a virtual environment keeps yours apart.
mise [installs tools such as Node.js, Python, and Go](https://mise.jdx.dev/dev-tools/) and selects their versions per project, so one tool covers Python and the rest of your stack. In a project, `mise use python@<version>` [writes that version to a `mise.toml` file](https://mise.jdx.dev/lang/python.html#quick-start). [Commit the file](https://mise.jdx.dev/getting-started.html#share-the-project), and teammates and CI get the same tools with `mise install`. To also create and activate the project's virtual environment, add [`_.python.venv`](https://mise.jdx.dev/lang/python.html#automatic-virtualenv-activation) to the file's `[env]` section. [Activate mise in your shell](https://mise.jdx.dev/getting-started.html#activate-mise), and entering the project puts its Python on your `PATH`.
Whichever tools you combine, name each project's Python in a `.python-version` file. `pyenv local` [writes that file](https://github.com/pyenv/pyenv#understanding-python-version-selection), and so does `uv python pin`, whose docs [recommend a plain version number](https://docs.astral.sh/uv/concepts/python-versions/#python-version-files) there so other tools can read it. mise reads the file too, once you [enable it for Python](https://mise.jdx.dev/lang/python.html#version-files). virtualenv [uses the version pyenv selected](https://virtualenv.pypa.io/en/latest/how-to/usage.html#using-version-managers-pyenv-mise-asdf) with no extra configuration. Don't install packages into the Python that came with your operating system, which [often manages its packages itself](https://docs.astral.sh/uv/pip/environments/); a virtual environment keeps yours apart.