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.py`
13
14.. index::
15   single: configuration information
16
17--------------
18
19The :mod:`sysconfig` module provides access to Python's configuration
20information like the list of installation paths and the configuration variables
21relevant for the current platform.
22
23Configuration variables
24-----------------------
25
26A Python distribution contains a :file:`Makefile` and a :file:`pyconfig.h`
27header file that are necessary to build both the Python binary itself and
28third-party C extensions compiled using :mod:`distutils`.
29
30:mod:`sysconfig` puts all variables found in these files in a dictionary that
31can be accessed using :func:`get_config_vars` or :func:`get_config_var`.
32
33Notice that on Windows, it's a much smaller set.
34
35.. function:: get_config_vars(*args)
36
37   With no arguments, return a dictionary of all configuration variables
38   relevant for the current platform.
39
40   With arguments, return a list of values that result from looking up each
41   argument in the configuration variable dictionary.
42
43   For each argument, if the value is not found, return ``None``.
44
45
46.. function:: get_config_var(name)
47
48   Return the value of a single variable *name*. Equivalent to
49   ``get_config_vars().get(name)``.
50
51   If *name* is not found, return ``None``.
52
53Example of usage::
54
55   >>> import sysconfig
56   >>> sysconfig.get_config_var('Py_ENABLE_SHARED')
57   0
58   >>> sysconfig.get_config_var('LIBDIR')
59   '/usr/local/lib'
60   >>> sysconfig.get_config_vars('AR', 'CXX')
61   ['ar', 'g++']
62
63.. _installation_paths:
64
65Installation paths
66------------------
67
68Python uses an installation scheme that differs depending on the platform and on
69the installation options.  These schemes are stored in :mod:`sysconfig` under
70unique identifiers based on the value returned by :const:`os.name`.
71
72Every new component that is installed using :mod:`distutils` or a
73Distutils-based system will follow the same scheme to copy its file in the right
74places.
75
76Python currently supports nine schemes:
77
78- *posix_prefix*: scheme for POSIX platforms like Linux or macOS.  This is
79  the default scheme used when Python or a component is installed.
80- *posix_home*: scheme for POSIX platforms used when a *home* option is used
81  upon installation.  This scheme is used when a component is installed through
82  Distutils with a specific home prefix.
83- *posix_user*: scheme for POSIX platforms used when a component is installed
84  through Distutils and the *user* option is used.  This scheme defines paths
85  located under the user home directory.
86- *posix_venv*: scheme for :mod:`Python virtual environments <venv>` on POSIX
87  platforms; by default it is the same as *posix_prefix* .
88- *nt*: scheme for NT platforms like Windows.
89- *nt_user*: scheme for NT platforms, when the *user* option is used.
90- *nt_venv*: scheme for :mod:`Python virtual environments <venv>` on NT
91  platforms; by default it is the same as *nt* .
92- *venv*: a scheme with values from ether *posix_venv* or *nt_venv* depending
93  on the platform Python runs on
94- *osx_framework_user*: scheme for macOS, when the *user* option is used.
95
96Each scheme is itself composed of a series of paths and each path has a unique
97identifier.  Python currently uses eight paths:
98
99- *stdlib*: directory containing the standard Python library files that are not
100  platform-specific.
101- *platstdlib*: directory containing the standard Python library files that are
102  platform-specific.
103- *platlib*: directory for site-specific, platform-specific files.
104- *purelib*: directory for site-specific, non-platform-specific files.
105- *include*: directory for non-platform-specific header files for
106  the Python C-API.
107- *platinclude*: directory for platform-specific header files for
108  the Python C-API.
109- *scripts*: directory for script files.
110- *data*: directory for data files.
111
112:mod:`sysconfig` provides some functions to determine these paths.
113
114.. function:: get_scheme_names()
115
116   Return a tuple containing all schemes currently supported in
117   :mod:`sysconfig`.
118
119
120.. function:: get_default_scheme()
121
122   Return the default scheme name for the current platform.
123
124   .. versionadded:: 3.10
125      This function was previously named ``_get_default_scheme()`` and
126      considered an implementation detail.
127
128   .. versionchanged:: 3.11
129      When Python runs from a virtual environment,
130      the *venv* scheme is returned.
131
132.. function:: get_preferred_scheme(key)
133
134   Return a preferred scheme name for an installation layout specified by *key*.
135
136   *key* must be either ``"prefix"``, ``"home"``, or ``"user"``.
137
138   The return value is a scheme name listed in :func:`get_scheme_names`. It
139   can be passed to :mod:`sysconfig` functions that take a *scheme* argument,
140   such as :func:`get_paths`.
141
142   .. versionadded:: 3.10
143
144   .. versionchanged:: 3.11
145      When Python runs from a virtual environment and ``key="prefix"``,
146      the *venv* scheme is returned.
147
148
149.. function:: _get_preferred_schemes()
150
151   Return a dict containing preferred scheme names on the current platform.
152   Python implementers and redistributors may add their preferred schemes to
153   the ``_INSTALL_SCHEMES`` module-level global value, and modify this function
154   to return those scheme names, to e.g. provide different schemes for system
155   and language package managers to use, so packages installed by either do not
156   mix with those by the other.
157
158   End users should not use this function, but :func:`get_default_scheme` and
159   :func:`get_preferred_scheme()` instead.
160
161   .. versionadded:: 3.10
162
163
164.. function:: get_path_names()
165
166   Return a tuple containing all path names currently supported in
167   :mod:`sysconfig`.
168
169
170.. function:: get_path(name, [scheme, [vars, [expand]]])
171
172   Return an installation path corresponding to the path *name*, from the
173   install scheme named *scheme*.
174
175   *name* has to be a value from the list returned by :func:`get_path_names`.
176
177   :mod:`sysconfig` stores installation paths corresponding to each path name,
178   for each platform, with variables to be expanded.  For instance the *stdlib*
179   path for the *nt* scheme is: ``{base}/Lib``.
180
181   :func:`get_path` will use the variables returned by :func:`get_config_vars`
182   to expand the path.  All variables have default values for each platform so
183   one may call this function and get the default value.
184
185   If *scheme* is provided, it must be a value from the list returned by
186   :func:`get_scheme_names`.  Otherwise, the default scheme for the current
187   platform is used.
188
189   If *vars* is provided, it must be a dictionary of variables that will update
190   the dictionary return by :func:`get_config_vars`.
191
192   If *expand* is set to ``False``, the path will not be expanded using the
193   variables.
194
195   If *name* is not found, raise a :exc:`KeyError`.
196
197
198.. function:: get_paths([scheme, [vars, [expand]]])
199
200   Return a dictionary containing all installation paths corresponding to an
201   installation scheme. See :func:`get_path` for more information.
202
203   If *scheme* is not provided, will use the default scheme for the current
204   platform.
205
206   If *vars* is provided, it must be a dictionary of variables that will
207   update the dictionary used to expand the paths.
208
209   If *expand* is set to false, the paths will not be expanded.
210
211   If *scheme* is not an existing scheme, :func:`get_paths` will raise a
212   :exc:`KeyError`.
213
214
215Other functions
216---------------
217
218.. function:: get_python_version()
219
220   Return the ``MAJOR.MINOR`` Python version number as a string.  Similar to
221   ``'%d.%d' % sys.version_info[:2]``.
222
223
224.. function:: get_platform()
225
226   Return a string that identifies the current platform.
227
228   This is used mainly to distinguish platform-specific build directories and
229   platform-specific built distributions.  Typically includes the OS name and
230   version and the architecture (as supplied by 'os.uname()'), although the
231   exact information included depends on the OS; e.g., on Linux, the kernel
232   version isn't particularly important.
233
234   Examples of returned values:
235
236   - linux-i586
237   - linux-alpha (?)
238   - solaris-2.6-sun4u
239
240   Windows will return one of:
241
242   - win-amd64 (64bit Windows on AMD64, aka x86_64, Intel64, and EM64T)
243   - win32 (all others - specifically, sys.platform is returned)
244
245   macOS can return:
246
247   - macosx-10.6-ppc
248   - macosx-10.4-ppc64
249   - macosx-10.3-i386
250   - macosx-10.4-fat
251
252   For other non-POSIX platforms, currently just returns :data:`sys.platform`.
253
254
255.. function:: is_python_build()
256
257   Return ``True`` if the running Python interpreter was built from source and
258   is being run from its built location, and not from a location resulting from
259   e.g. running ``make install`` or installing via a binary installer.
260
261
262.. function:: parse_config_h(fp[, vars])
263
264   Parse a :file:`config.h`\-style file.
265
266   *fp* is a file-like object pointing to the :file:`config.h`\-like file.
267
268   A dictionary containing name/value pairs is returned.  If an optional
269   dictionary is passed in as the second argument, it is used instead of a new
270   dictionary, and updated with the values read in the file.
271
272
273.. function:: get_config_h_filename()
274
275   Return the path of :file:`pyconfig.h`.
276
277.. function:: get_makefile_filename()
278
279   Return the path of :file:`Makefile`.
280
281
282Using :mod:`sysconfig` as a script
283----------------------------------
284
285You can use :mod:`sysconfig` as a script with Python's *-m* option:
286
287.. code-block:: shell-session
288
289    $ python -m sysconfig
290    Platform: "macosx-10.4-i386"
291    Python version: "3.2"
292    Current installation scheme: "posix_prefix"
293
294    Paths:
295            data = "/usr/local"
296            include = "/Users/tarek/Dev/svn.python.org/py3k/Include"
297            platinclude = "."
298            platlib = "/usr/local/lib/python3.2/site-packages"
299            platstdlib = "/usr/local/lib/python3.2"
300            purelib = "/usr/local/lib/python3.2/site-packages"
301            scripts = "/usr/local/bin"
302            stdlib = "/usr/local/lib/python3.2"
303
304    Variables:
305            AC_APPLE_UNIVERSAL_BUILD = "0"
306            AIX_GENUINE_CPLUSPLUS = "0"
307            AR = "ar"
308            ARFLAGS = "rc"
309            ...
310
311This call will print in the standard output the information returned by
312:func:`get_platform`, :func:`get_python_version`, :func:`get_path` and
313:func:`get_config_vars`.
314