Debian Codegraph @

Doc/library/sysconfig.rst

raw
1 :mod:`!sysconfig` --- Provide access to Python's configuration information
2 ==========================================================================
3
4 .. module:: sysconfig
5 :synopsis: Python's configuration information
6
7 .. moduleauthor:: Tarek Ziadé <[email protected]>
8 .. sectionauthor:: Tarek Ziadé <[email protected]>
9
10 .. versionadded:: 3.2
11
12 **Source code:** :source:`Lib/sysconfig`
13
14 .. index::
15 single: configuration information
16
17 --------------
18
19 The :mod:`!sysconfig` module provides access to Python's configuration
20 information like the list of installation paths and the configuration variables
21 relevant for the current platform.
22
23
24 Configuration variables
25 -----------------------
26
27 A Python distribution contains a :file:`Makefile` and a :file:`pyconfig.h`
28 header file that are necessary to build both the Python binary itself and
29 third-party C extensions compiled using ``setuptools``.
30
31 :mod:`!sysconfig` puts all variables found in these files in a dictionary that
32 can be accessed using :func:`get_config_vars` or :func:`get_config_var`.
33
34 Notice that on Windows, it's a much smaller set.
35
36 .. function:: get_config_vars(*args)
37
38 With no arguments, return a dictionary of all configuration variables
39 relevant for the current platform.
40
41 With arguments, return a list of values that result from looking up each
42 argument in the configuration variable dictionary.
43
44 For each argument, if the value is not found, return ``None``.
45
46
47 .. function:: get_config_var(name)
48
49 Return the value of a single variable *name*. Equivalent to
50 ``get_config_vars().get(name)``.
51
52 If *name* is not found, return ``None``.
53
54 Example of usage::
55
56 >>> import sysconfig
57 >>> sysconfig.get_config_var('Py_ENABLE_SHARED')
58 0
59 >>> sysconfig.get_config_var('LIBDIR')
60 '/usr/local/lib'
61 >>> sysconfig.get_config_vars('AR', 'CXX')
62 ['ar', 'g++']
63
64
65 .. _installation_paths:
66
67 Installation paths
68 ------------------
69
70 Python uses an installation scheme that differs depending on the platform and on
71 the installation options. These schemes are stored in :mod:`!sysconfig` under
72 unique identifiers based on the value returned by :const:`os.name`.
73 The schemes are used by package installers to determine where to copy files to.
74
75 Python currently supports nine schemes:
76
77 - *posix_prefix*: scheme for POSIX platforms like Linux or macOS. This is
78 the default scheme used when Python or a component is installed.
79 - *posix_home*: scheme for POSIX platforms, when the *home* option is used.
80 This scheme defines paths located under a specific home prefix.
81 - *posix_user*: scheme for POSIX platforms, when the *user* option is used.
82 This scheme defines paths located under the user's home directory
83 (:const:`site.USER_BASE`).
84 - *posix_venv*: scheme for :mod:`Python virtual environments <venv>` on POSIX
85 platforms; by default it is the same as *posix_prefix*.
86 - *nt*: scheme for Windows.
87 This is the default scheme used when Python or a component is installed.
88 - *nt_user*: scheme for Windows, when the *user* option is used.
89 - *nt_venv*: scheme for :mod:`Python virtual environments <venv>` on Windows;
90 by default it is the same as *nt*.
91 - *venv*: a scheme with values from either *posix_venv* or *nt_venv* depending
92 on the platform Python runs on.
93 - *osx_framework_user*: scheme for macOS, when the *user* option is used.
94
95 Each scheme is itself composed of a series of paths and each path has a unique
96 identifier. Python currently uses eight paths:
97
98 - *stdlib*: directory containing the standard Python library files that are not
99 platform-specific.
100 - *platstdlib*: directory containing the standard Python library files that are
101 platform-specific.
102 - *platlib*: directory for site-specific, platform-specific files.
103 - *purelib*: directory for site-specific, non-platform-specific files ('pure' Python).
104 - *include*: directory for non-platform-specific header files for
105 the Python C-API.
106 - *platinclude*: directory for platform-specific header files for
107 the Python C-API.
108 - *scripts*: directory for script files.
109 - *data*: directory for data files.
110
111
112 .. _sysconfig-user-scheme:
113
114 User scheme
115 ---------------
116
117 This scheme is designed to be the most convenient solution for users that don't
118 have write permission to the global site-packages directory or don't want to
119 install into it.
120
121 Files will be installed into subdirectories of :const:`site.USER_BASE` (written
122 as :file:`{userbase}` hereafter). This scheme installs pure Python modules and
123 extension modules in the same location (also known as :const:`site.USER_SITE`).
124
125 ``posix_user``
126 ^^^^^^^^^^^^^^
127
128 ============== ===========================================================
129 Path Installation directory
130 ============== ===========================================================
131 *stdlib* :file:`{userbase}/lib/python{X.Y}`
132 *platstdlib* :file:`{userbase}/lib/python{X.Y}`
133 *platlib* :file:`{userbase}/lib/python{X.Y}/site-packages`
134 *purelib* :file:`{userbase}/lib/python{X.Y}/site-packages`
135 *include* :file:`{userbase}/include/python{X.Y}`
136 *scripts* :file:`{userbase}/bin`
137 *data* :file:`{userbase}`
138 ============== ===========================================================
139
140 ``nt_user``
141 ^^^^^^^^^^^
142
143 ============== ===========================================================
144 Path Installation directory
145 ============== ===========================================================
146 *stdlib* :file:`{userbase}\\Python{XY}`
147 *platstdlib* :file:`{userbase}\\Python{XY}`
148 *platlib* :file:`{userbase}\\Python{XY}\\site-packages`
149 *purelib* :file:`{userbase}\\Python{XY}\\site-packages`
150 *include* :file:`{userbase}\\Python{XY}\\Include`
151 *scripts* :file:`{userbase}\\Python{XY}\\Scripts`
152 *data* :file:`{userbase}`
153 ============== ===========================================================
154
155 ``osx_framework_user``
156 ^^^^^^^^^^^^^^^^^^^^^^
157
158 ============== ===========================================================
159 Path Installation directory
160 ============== ===========================================================
161 *stdlib* :file:`{userbase}/lib/python`
162 *platstdlib* :file:`{userbase}/lib/python`
163 *platlib* :file:`{userbase}/lib/python/site-packages`
164 *purelib* :file:`{userbase}/lib/python/site-packages`
165 *include* :file:`{userbase}/include/python{X.Y}`
166 *scripts* :file:`{userbase}/bin`
167 *data* :file:`{userbase}`
168 ============== ===========================================================
169
170
171 .. _sysconfig-home-scheme:
172
173 Home scheme
174 -----------
175
176 The idea behind the "home scheme" is that you build and maintain a personal
177 stash of Python modules. This scheme's name is derived from the idea of a
178 "home" directory on Unix, since it's not unusual for a Unix user to make their
179 home directory have a layout similar to :file:`/usr/` or :file:`/usr/local/`.
180 This scheme can be used by anyone, regardless of the operating system they
181 are installing for.
182
183 ``posix_home``
184 ^^^^^^^^^^^^^^
185
186 ============== ===========================================================
187 Path Installation directory
188 ============== ===========================================================
189 *stdlib* :file:`{home}/lib/python`
190 *platstdlib* :file:`{home}/lib/python`
191 *platlib* :file:`{home}/lib/python`
192 *purelib* :file:`{home}/lib/python`
193 *include* :file:`{home}/include/python`
194 *platinclude* :file:`{home}/include/python`
195 *scripts* :file:`{home}/bin`
196 *data* :file:`{home}`
197 ============== ===========================================================
198
199
200 .. _sysconfig-prefix-scheme:
201
202 Prefix scheme
203 -------------
204
205 The "prefix scheme" is useful when you wish to use one Python installation to
206 perform the build/install (i.e., to run the setup script), but install modules
207 into the third-party module directory of a different Python installation (or
208 something that looks like a different Python installation). If this sounds a
209 trifle unusual, it is---that's why the user and home schemes come before. However,
210 there are at least two known cases where the prefix scheme will be useful.
211
212 First, consider that many Linux distributions put Python in :file:`/usr`, rather
213 than the more traditional :file:`/usr/local`. This is entirely appropriate,
214 since in those cases Python is part of "the system" rather than a local add-on.
215 However, if you are installing Python modules from source, you probably want
216 them to go in :file:`/usr/local/lib/python2.{X}` rather than
217 :file:`/usr/lib/python2.{X}`.
218
219 Another possibility is a network filesystem where the name used to write to a
220 remote directory is different from the name used to read it: for example, the
221 Python interpreter accessed as :file:`/usr/local/bin/python` might search for
222 modules in :file:`/usr/local/lib/python2.{X}`, but those modules would have to
223 be installed to, say, :file:`/mnt/{@server}/export/lib/python2.{X}`.
224
225 ``posix_prefix``
226 ^^^^^^^^^^^^^^^^
227
228 ============== ==========================================================
229 Path Installation directory
230 ============== ==========================================================
231 *stdlib* :file:`{prefix}/lib/python{X.Y}`
232 *platstdlib* :file:`{prefix}/lib/python{X.Y}`
233 *platlib* :file:`{prefix}/lib/python{X.Y}/site-packages`
234 *purelib* :file:`{prefix}/lib/python{X.Y}/site-packages`
235 *include* :file:`{prefix}/include/python{X.Y}`
236 *platinclude* :file:`{prefix}/include/python{X.Y}`
237 *scripts* :file:`{prefix}/bin`
238 *data* :file:`{prefix}`
239 ============== ==========================================================
240
241 ``nt``
242 ^^^^^^
243
244 ============== ==========================================================
245 Path Installation directory
246 ============== ==========================================================
247 *stdlib* :file:`{prefix}\\Lib`
248 *platstdlib* :file:`{prefix}\\Lib`
249 *platlib* :file:`{prefix}\\Lib\\site-packages`
250 *purelib* :file:`{prefix}\\Lib\\site-packages`
251 *include* :file:`{prefix}\\Include`
252 *platinclude* :file:`{prefix}\\Include`
253 *scripts* :file:`{prefix}\\Scripts`
254 *data* :file:`{prefix}`
255 ============== ==========================================================
256
257
258 Installation path functions
259 ---------------------------
260
261 :mod:`!sysconfig` provides some functions to determine these installation paths.
262
263 .. function:: get_scheme_names()
264
265 Return a tuple containing all schemes currently supported in
266 :mod:`!sysconfig`.
267
268
269 .. function:: get_default_scheme()
270
271 Return the default scheme name for the current platform.
272
273 .. versionadded:: 3.10
274 This function was previously named ``_get_default_scheme()`` and
275 considered an implementation detail.
276
277 .. versionchanged:: 3.11
278 When Python runs from a virtual environment,
279 the *venv* scheme is returned.
280
281 .. function:: get_preferred_scheme(key)
282
283 Return a preferred scheme name for an installation layout specified by *key*.
284
285 *key* must be either ``"prefix"``, ``"home"``, or ``"user"``.
286
287 The return value is a scheme name listed in :func:`get_scheme_names`. It
288 can be passed to :mod:`!sysconfig` functions that take a *scheme* argument,
289 such as :func:`get_paths`.
290
291 .. versionadded:: 3.10
292
293 .. versionchanged:: 3.11
294 When Python runs from a virtual environment and ``key="prefix"``,
295 the *venv* scheme is returned.
296
297
298 .. function:: _get_preferred_schemes()
299
300 Return a dict containing preferred scheme names on the current platform.
301 Python implementers and redistributors may add their preferred schemes to
302 the ``_INSTALL_SCHEMES`` module-level global value, and modify this function
303 to return those scheme names, to e.g. provide different schemes for system
304 and language package managers to use, so packages installed by either do not
305 mix with those by the other.
306
307 End users should not use this function, but :func:`get_default_scheme` and
308 :func:`get_preferred_scheme` instead.
309
310 .. versionadded:: 3.10
311
312
313 .. function:: get_path_names()
314
315 Return a tuple containing all path names currently supported in
316 :mod:`!sysconfig`.
317
318
319 .. function:: get_path(name, [scheme, [vars, [expand]]])
320
321 Return an installation path corresponding to the path *name*, from the
322 install scheme named *scheme*.
323
324 *name* has to be a value from the list returned by :func:`get_path_names`.
325
326 :mod:`!sysconfig` stores installation paths corresponding to each path name,
327 for each platform, with variables to be expanded. For instance the *stdlib*
328 path for the *nt* scheme is: ``{base}/Lib``.
329
330 :func:`get_path` will use the variables returned by :func:`get_config_vars`
331 to expand the path. All variables have default values for each platform so
332 one may call this function and get the default value.
333
334 If *scheme* is provided, it must be a value from the list returned by
335 :func:`get_scheme_names`. Otherwise, the default scheme for the current
336 platform is used.
337
338 If *vars* is provided, it must be a dictionary of variables that will update
339 the dictionary returned by :func:`get_config_vars`.
340
341 If *expand* is set to ``False``, the path will not be expanded using the
342 variables.
343
344 If *name* is not found, raise a :exc:`KeyError`.
345
346
347 .. function:: get_paths([scheme, [vars, [expand]]])
348
349 Return a dictionary containing all installation paths corresponding to an
350 installation scheme. See :func:`get_path` for more information.
351
352 If *scheme* is not provided, will use the default scheme for the current
353 platform.
354
355 If *vars* is provided, it must be a dictionary of variables that will
356 update the dictionary used to expand the paths.
357
358 If *expand* is set to false, the paths will not be expanded.
359
360 If *scheme* is not an existing scheme, :func:`get_paths` will raise a
361 :exc:`KeyError`.
362
363
364 Other functions
365 ---------------
366
367 .. function:: get_python_version()
368
369 Return the ``MAJOR.MINOR`` Python version number as a string. Similar to
370 ``'%d.%d' % sys.version_info[:2]``.
371
372
373 .. function:: get_platform()
374
375 Return a string that identifies the current platform.
376
377 This is used mainly to distinguish platform-specific build directories and
378 platform-specific built distributions. Typically includes the OS name and
379 version and the architecture (as supplied by :func:`os.uname`), although the
380 exact information included depends on the OS; e.g., on Linux, the kernel
381 version isn't particularly important.
382
383 Examples of returned values:
384
385
386 Windows:
387
388 - win-amd64 (64-bit Windows on AMD64, aka x86_64, Intel64, and EM64T)
389 - win-arm64 (64-bit Windows on ARM64, aka AArch64)
390 - win32 (all others - specifically, sys.platform is returned)
391
392 POSIX based OS:
393
394 - linux-x86_64
395 - macosx-15.5-arm64
396 - macosx-26.0-universal2 (macOS on Apple Silicon or Intel)
397 - android-24-arm64_v8a
398
399 For other non-POSIX platforms, currently just returns :data:`sys.platform`.
400
401
402 .. function:: is_python_build()
403
404 Return ``True`` if the running Python interpreter was built from source and
405 is being run from its built location, and not from a location resulting from
406 e.g. running ``make install`` or installing via a binary installer.
407
408
409 .. function:: parse_config_h(fp[, vars])
410
411 Parse a :file:`config.h`\-style file.
412
413 *fp* is a file-like object pointing to the :file:`config.h`\-like file.
414
415 A dictionary containing name/value pairs is returned. If an optional
416 dictionary is passed in as the second argument, it is used instead of a new
417 dictionary, and updated with the values read in the file.
418
419
420 .. function:: get_config_h_filename()
421
422 Return the path of :file:`pyconfig.h`.
423
424 .. function:: get_makefile_filename()
425
426 Return the path of :file:`Makefile`.
427
428 .. _sysconfig-cli:
429 .. _using-sysconfig-as-a-script:
430
431 Command-line usage
432 ------------------
433
434 You can use :mod:`!sysconfig` as a script with Python's *-m* option:
435
436 .. code-block:: shell-session
437
438 $ python -m sysconfig
439 Platform: "macosx-10.4-i386"
440 Python version: "3.2"
441 Current installation scheme: "posix_prefix"
442
443 Paths:
444 data = "/usr/local"
445 include = "/Users/tarek/Dev/svn.python.org/py3k/Include"
446 platinclude = "."
447 platlib = "/usr/local/lib/python3.2/site-packages"
448 platstdlib = "/usr/local/lib/python3.2"
449 purelib = "/usr/local/lib/python3.2/site-packages"
450 scripts = "/usr/local/bin"
451 stdlib = "/usr/local/lib/python3.2"
452
453 Variables:
454 AC_APPLE_UNIVERSAL_BUILD = "0"
455 AIX_GENUINE_CPLUSPLUS = "0"
456 AR = "ar"
457 ARFLAGS = "rc"
458 ...
459
460 This call will print in the standard output the information returned by
461 :func:`get_platform`, :func:`get_python_version`, :func:`get_path` and
462 :func:`get_config_vars`.