Debian Codegraph @

docs/tutorial/getting-started.rst

raw
1 .. _getting_started:
2
3 #################
4 Getting Started
5 #################
6
7 This tutorial walks you through creating your first tox project from scratch. By the end, you will have a working tox
8 configuration that runs tests and linting across multiple Python versions.
9
10 ***************
11 Prerequisites
12 ***************
13
14 Before starting, make sure you have:
15
16 - Python 3.10 or later installed
17 - tox installed (see :doc:`../how-to/install`)
18 - A Python project you want to test (or follow along to create one)
19
20 Verify tox is available:
21
22 .. code-block:: bash
23
24 tox --version
25
26 ***********************************
27 Creating your first configuration
28 ***********************************
29
30 tox needs a configuration file where you define what tools to run and how to set up environments for them. tox supports
31 two configuration formats: TOML and INI. **TOML is the recommended format for new projects** -- it is more robust, has
32 proper type support, and avoids ambiguities inherent in INI parsing. INI remains supported for existing projects.
33
34 Create a ``tox.toml`` (or ``tox.ini``) at the root of your project:
35
36 .. tab:: TOML
37
38 .. code-block:: toml
39
40 env_list = ["3.13", "3.12", "lint"]
41
42 [env_run_base]
43 description = "run the test suite with pytest"
44 deps = [
45 "pytest>=8",
46 ]
47 commands = [["pytest", { replace = "posargs", default = ["tests"], extend = true }]]
48
49 [env.lint]
50 description = "run linters"
51 skip_install = true
52 deps = ["ruff"]
53 commands = [["ruff", "check", { replace = "posargs", default = ["."], extend = true }]]
54
55 .. tab:: INI
56
57 .. code-block:: ini
58
59 [tox]
60 env_list = 3.13, 3.12, lint
61
62 [testenv]
63 description = run the test suite with pytest
64 deps =
65 pytest>=8
66 commands =
67 pytest {posargs:tests}
68
69 [testenv:lint]
70 description = run linters
71 skip_install = true
72 deps =
73 ruff
74 commands = ruff check {posargs:.}
75
76 .. tip::
77
78 You can also generate a ``tox.ini`` file automatically by running ``tox quickstart`` and answering a few questions.
79
80 *********************************
81 Understanding the configuration
82 *********************************
83
84 The configuration has two parts: **core settings** and **environment settings**.
85
86 Core settings
87 =============
88
89 Core settings affect all environments or configure how tox itself behaves. They live at the root level in ``tox.toml``
90 (or under the ``[tox]`` section in ``tox.ini``).
91
92 .. tab:: TOML
93
94 .. code-block:: toml
95
96 env_list = ["3.13", "3.12", "lint"]
97
98 .. tab:: INI
99
100 .. code-block:: ini
101
102 [tox]
103 env_list = 3.13, 3.12, lint
104
105 The :ref:`env_list` setting defines which environments run by default when you invoke ``tox`` without specifying any.
106 Both formats support generating environment matrices from factor combinations — INI uses curly-brace expansion
107 (``3.{10-}``), while TOML composes from structured dicts. A single axis is a bare range dict (``{ prefix = "3.", start =
108 10 }``); multi-dimensional matrices use a ``product`` dict. See :ref:`generative-environment-list` for details. For the
109 full list of core options, see :ref:`conf-core`.
110
111 Environment settings
112 ====================
113
114 Each tox environment has its own configuration. Settings defined at the base level (``env_run_base`` in TOML,
115 ``testenv`` in INI) are inherited by all environments unless overridden. Individual environments are configured under
116 ``env.<name>`` in TOML or ``testenv:<name>`` in INI.
117
118 .. tab:: TOML
119
120 .. code-block:: toml
121
122 [env_run_base]
123 description = "run the test suite with pytest"
124 deps = ["pytest>=8"]
125 commands = [["pytest", { replace = "posargs", default = ["tests"], extend = true }]]
126
127 [env.lint]
128 description = "run linters"
129 skip_install = true
130 deps = ["ruff"]
131 commands = [["ruff", "check", "."]]
132
133 .. tab:: INI
134
135 .. code-block:: ini
136
137 [testenv]
138 description = run the test suite with pytest
139 deps =
140 pytest>=8
141 commands =
142 pytest {posargs:tests}
143
144 [testenv:lint]
145 description = run linters
146 skip_install = true
147 deps =
148 ruff
149 commands = ruff check .
150
151 Here the ``lint`` environment overrides the base settings entirely, while ``3.13`` and ``3.12`` inherit from the base.
152
153 .. tip::
154
155 Options must go in the correct section — placing a core option in an environment section (or vice versa) silently
156 has no effect. Run ``tox run -v`` or ``tox config`` to check for misplaced keys.
157
158 Environment names and Python versions
159 =====================================
160
161 Environment names can consist of alphanumeric characters, dashes, and dots. Names are split on dashes into **factors**
162 -- for example ``py311-django42`` splits into factors ``py311`` and ``django42``. Additionally, the current platform
163 (like ``linux``, ``darwin``, ``win32``) is automatically available as an implicit factor for conditional configuration.
164
165 tox recognizes certain naming patterns and automatically sets the Python interpreter:
166
167 - ``N.M``: CPython N.M (e.g. ``3.13``) -- **preferred**
168 - ``pyNM`` or ``pyN.M``: CPython N.M (e.g. ``py313`` or ``py3.13``) -- legacy, still supported
169 - ``pypyNM``: PyPy N.M
170 - ``cpythonNM``: CPython N.M
171 - ``graalpyNM``: GraalPy N.M
172
173 Prefer the ``N.M`` form (e.g. ``3.14``) over ``pyNMM`` (e.g. ``py314``). The dotted form is unambiguous, reads more
174 naturally in environment lists and CI output, and avoids confusion for Python versions >= 3.10 where the concatenated
175 digits become three characters.
176
177 .. note::
178
179 Version-number factors like ``3.14`` can be checked in conditional expressions using subscript syntax:
180 ``factor['3.14']`` (the dot-syntax ``factor.3.14`` would be a syntax error). See :ref:`conditional-value-reference`
181 for details.
182
183 If the name doesn't match any pattern, tox uses the same Python as the one tox is installed into (this is the case for
184 ``lint`` in our example). To override this fallback, set :ref:`default_base_python`:
185
186 .. code-block:: toml
187
188 [env_run_base]
189 default_base_python = ["3.14", "3.13"]
190
191 This pins a default Python version for environments without a Python factor, improving reproducibility across machines
192 with different system Pythons.
193
194 .. tip::
195
196 If your project uses :PEP:`751` lock files (``pylock.toml``), you can install locked dependencies via :ref:`pylock`
197 instead of listing packages in ``deps``.
198
199 For the full list of environment options, see :ref:`conf-testenv`.
200
201 Scaling to multiple Python versions
202 ===================================
203
204 When your test matrix grows beyond a few environments, use ``env_base`` sections to define named templates that generate
205 environments from factor combinations:
206
207 .. code-block:: toml
208
209 [env_base.test]
210 factors = [["3.13", "3.14"]]
211 deps = ["pytest>=8"]
212 commands = [["pytest"]]
213
214 This generates ``test-3.13`` and ``test-3.14``, each inheriting deps and commands from the template. The template itself
215 inherits from ``env_run_base``, so global defaults still apply. See :ref:`env-base-templates` for details.
216
217 ***************************
218 Running your environments
219 ***************************
220
221 Run all default environments (those listed in :ref:`env_list`):
222
223 .. code-block:: bash
224
225 tox
226
227 Run a specific environment:
228
229 .. code-block:: bash
230
231 tox run -e lint
232
233 Run multiple environments:
234
235 .. code-block:: bash
236
237 tox run -e 3.13,lint
238
239 Pass extra arguments to the underlying tool using ``--``:
240
241 .. code-block:: bash
242
243 # Run pytest in verbose mode
244 tox run -e 3.13 -- -v
245
246 # Run ruff on a specific file
247 tox run -e lint -- src/mymodule.py
248
249 The ``{ replace = "posargs" }`` in TOML (or ``{posargs}`` in INI) is a placeholder that gets replaced by whatever you
250 pass after ``--``.
251
252 **************************
253 Understanding the output
254 **************************
255
256 On the first run, tox creates virtual environments and installs dependencies. Subsequent runs reuse existing
257 environments unless dependencies change:
258
259 .. code-block:: bash
260
261 $ tox run -e 3.13,lint
262 3.13: install_deps> python -m pip install 'pytest>=8'
263 3.13: commands[0]> pytest tests
264 ========================= 3 passed in 0.12s =========================
265 3.13: OK ✔ in 5.43s
266 lint: install_deps> python -m pip install ruff
267 lint: commands[0]> ruff check .
268 All checks passed!
269 lint: OK ✔ in 2.11s
270
271 3.13: OK (5.43=setup[3.21]+cmd[2.22] seconds)
272 lint: OK (2.11=setup[1.05]+cmd[1.06] seconds)
273 congratulations :)
274
275 tox will automatically detect changes to your dependencies and recreate environments when needed. You can force a full
276 recreation with the ``-r`` flag:
277
278 .. code-block:: bash
279
280 tox run -e 3.13 -r
281
282 If tools inside the environment maintain their own caches (e.g. pre-commit), you can use :ref:`recreate_commands` to
283 clean them before the environment directory is removed. See :ref:`howto_clean_caches` for details.
284
285 If you want to rerun tests without reinstalling dependencies or the package (e.g. when working offline or when nothing
286 has changed), use ``--skip-env-install``:
287
288 .. code-block:: bash
289
290 tox run -e 3.13 --skip-env-install
291
292 ********************************
293 Listing available environments
294 ********************************
295
296 See all configured environments and their descriptions:
297
298 .. code-block:: bash
299
300 $ tox list
301 default environments:
302 3.13 -> run the test suite with pytest
303 3.12 -> run the test suite with pytest
304 lint -> run linters
305
306 **************************
307 Inspecting configuration
308 **************************
309
310 View the resolved configuration for an environment:
311
312 .. code-block:: bash
313
314 tox config -e 3.13 -k deps commands
315
316 The output format can be changed with ``--format`` and written to a file with ``-o``:
317
318 .. code-block:: bash
319
320 tox config -e 3.13 --format json -o config.json
321 tox config -e 3.13 --format toml -o config.toml
322
323 This is useful for debugging configuration issues and for programmatic consumption.
324
325 ************
326 Next steps
327 ************
328
329 Now that you have a working tox setup, explore these topics:
330
331 - :doc:`../explanation` -- understand how tox works (parallel mode, packaging, auto-provisioning)
332 - :doc:`../how-to/usage` -- practical recipes for common tasks (including testing across old and new Python versions
333 with :ref:`virtualenv_spec`)
334 - :ref:`configuration` -- full configuration reference
335 - :ref:`cli` -- complete CLI reference
336 - :ref:`howto_pep723` -- run standalone scripts with inline dependencies (:PEP:`723`)