Skip to content

Commit 57e0ece

Browse files
Google-ML-AutomationGoogle-ML-Automation
committed
Merge pull request #2569 from AI-Hypercomputer:bvandermoon-version-doc
PiperOrigin-RevId: 826247139
2 parents aebd278 + 5e1b120 commit 57e0ece

File tree

3 files changed

+63
-43
lines changed

3 files changed

+63
-43
lines changed

‎README.md‎

Lines changed: 1 addition & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -30,49 +30,7 @@ Check out our [Read The Docs site](https://maxtext.readthedocs.io/en/latest/) or
3030

3131
## Installation
3232

33-
We recommend installing MaxText inside a Python virtual environment.
34-
35-
### From PyPI (Recommended)
36-
This is the easiest way to get started with the latest stable version.
37-
38-
```bash
39-
# 1. Create virtual environment
40-
uv venv --python 3.12 --seed maxtext_venv
41-
source maxtext_venv/bin/activate
42-
43-
# 2. Install uv, a fast Python package installer
44-
pip install uv
45-
46-
# 3. Install MaxText and its dependencies
47-
uv pip install maxtext --resolution=lowest
48-
install_maxtext_github_deps
49-
```
50-
> **Note:** The `install_maxtext_github_deps` command is temporarily required to install dependencies directly from GitHub that are not yet available on PyPI.
51-
52-
> **Note:** The maxtext package contains a comprehensive list of all direct and transitive dependencies, with lower bounds, generated by [seed-env](https://github.com/google-ml-infra/actions/tree/main/python_seed_env). We highly recommend the `--resolution=lowest` flag. It instructs `uv` to install the specific, tested versions of dependencies defined by MaxText, rather than the latest available ones. This ensures a consistent and reproducible environment, which is critical for stable performance and for running benchmarks.
53-
54-
### From Source
55-
If you plan to contribute to MaxText or need the latest unreleased features, install from source.
56-
57-
```bash
58-
# 1. Clone the repository
59-
git clone https://github.com/AI-Hypercomputer/maxtext.git
60-
cd maxtext
61-
62-
# 2. Create virtual environment
63-
uv venv --python 3.12 --seed maxtext_venv
64-
source maxtext_venv/bin/activate
65-
66-
# 3. Install dependencies in editable mode
67-
pip install uv
68-
# install the tpu package
69-
uv pip install -e .[tpu] --resolution=lowest
70-
# or install the gpu package by running the following line
71-
# uv pip install -e .[cuda12] --resolution=lowest
72-
install_maxtext_github_deps
73-
```
74-
75-
After installation, you can verify the package is available with `python3 -c "import MaxText"` and run training jobs with `python3 -m MaxText.train ...`.
33+
See our installation guide to [install MaxText with pip](https://maxtext.readthedocs.io/en/latest/guides/install_maxtext.html).
7634

7735
## 🔥 Latest news 🔥
7836

‎docs/guides.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,4 +34,5 @@ guides/checkpointing_solutions.md
3434
guides/megascale_hang_playbook.md
3535
guides/multimodal.md
3636
guides/update_dependencies.md
37+
guides/install_maxtext.md
3738
```

‎docs/guides/install_maxtext.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
<!--
2+
Copyright 2023-2025 Google LLC
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
https://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
-->
16+
17+
# Installing MaxText
18+
19+
This document discusses how to install MaxText. We recommend installing MaxText inside a Python virtual environment.
20+
21+
## From PyPI (Recommended)
22+
This is the easiest way to get started with the latest stable version.
23+
24+
```bash
25+
# 1. Create virtual environment
26+
uv venv --python 3.12 --seed maxtext_venv
27+
source maxtext_venv/bin/activate
28+
29+
# 2. Install uv, a fast Python package installer
30+
pip install uv
31+
32+
# 3. Install MaxText and its dependencies
33+
uv pip install maxtext --resolution=lowest
34+
install_maxtext_github_deps
35+
```
36+
> **Note:** The `install_maxtext_github_deps` command is temporarily required to install dependencies directly from GitHub that are not yet available on PyPI.
37+
38+
> **Note:** The maxtext package contains a comprehensive list of all direct and transitive dependencies, with lower bounds, generated by [seed-env](https://github.com/google-ml-infra/actions/tree/main/python_seed_env). We highly recommend the `--resolution=lowest` flag. It instructs `uv` to install the specific, tested versions of dependencies defined by MaxText, rather than the latest available ones. This ensures a consistent and reproducible environment, which is critical for stable performance and for running benchmarks.
39+
40+
## From Source
41+
If you plan to contribute to MaxText or need the latest unreleased features, install from source.
42+
43+
```bash
44+
# 1. Clone the repository
45+
git clone https://github.com/AI-Hypercomputer/maxtext.git
46+
cd maxtext
47+
48+
# 2. Create virtual environment
49+
uv venv --python 3.12 --seed maxtext_venv
50+
source maxtext_venv/bin/activate
51+
52+
# 3. Install dependencies in editable mode
53+
pip install uv
54+
# install the tpu package
55+
uv pip install -e .[tpu] --resolution=lowest
56+
# or install the gpu package by running the following line
57+
# uv pip install -e .[cuda12] --resolution=lowest
58+
install_maxtext_github_deps
59+
```
60+
61+
After installation, you can verify the package is available with `python3 -c "import MaxText"` and run training jobs with `python3 -m MaxText.train ...`.

0 commit comments

Comments
 (0)