非官方中文翻译
本页译自 MNE-Python 官方文档：
查看英文原文 ↗。
文档版权归 MNE Developers 所有（BSD-3-Clause）。
说明
转到末尾下载完整示例代码。
配置 MNE-Python#
本教程介绍如何配置 MNE-Python，使其适配你的本地系统和分析偏好。
首先导入所需的 Python 模块：
# Authors: The MNE-Python contributors.
# License: BSD-3-Clause
# Copyright the MNE-Python contributors.
import os
import pandas as pd
import mne
获取与设置配置变量#
配置变量通过 mne.get_config() 和 mne.set_config() 函数读取和写入。要读取某个特定配置变量，请将其名称作为 key 参数传给 get_config()（key 是第一个参数，因此可以省略参数名）：
print(mne.get_config("MNE_USE_CUDA"))
None
如果系统中尚未设置所请求的键，上面的调用会返回 None。事实上，get_config() 从不会为可识别的键虚构默认值，它只报告 JSON 文件中或环境中实际存储的内容。另请注意，从 JSON 文件读取的字符串值不会被解析，因此即使配置值是 true/false，get_config() 也会返回字符串，而不是 Python 的 boolean。同样，set_config() 只能设置字符串值（或用于取消变量的 None 值）：
try:
mne.set_config("MNE_USE_CUDA", True)
except TypeError as err:
print(err)
value must be an instance of str, path-like, or NoneType, got <class 'bool'> instead.
如果不确定某个配置变量是否已设置，有一种便捷的方法可以检查它，并在其不存在时提供回退值：get_config() 具有 default 参数。
print(mne.get_config("missing_config_key", default="fallback value"))
fallback value
get_config() 还有两种便捷模式。第一种会返回一个 dict，其中包含系统中已设置的所有配置变量（及其值）；通过传入 key=None 即可实现（这是默认值，因此可以省略）：
print(mne.get_config()) # same as mne.get_config(key=None)
{'MNE_BROWSER_BACKEND': 'qt', 'MNE_3D_OPTION_THEME': 'light', 'MNE_BROWSER_OVERVIEW_MODE': 'hidden', 'MNE_BROWSER_THEME': 'light', 'MNE_BROWSER_PRECOMPUTE': 'false'}
第二种便捷模式会返回一个 dict，其中包含 MNE-Python 识别并使用的所有键，每个键映射到一段简短说明，无论这些键是否已在你的系统中设置。通过将空字符串作为 key 传入即可实现：
print(mne.get_config(key=""))
{'MNE_3D_OPTION_ANTIALIAS': 'bool, whether to use full-screen antialiasing in 3D plots', 'MNE_3D_OPTION_DEPTH_PEELING': 'bool, whether to use depth peeling in 3D plots', 'MNE_3D_OPTION_MULTI_SAMPLES': 'int, number of samples to use for full-screen antialiasing', 'MNE_3D_OPTION_SMOOTH_SHADING': 'bool, whether to use smooth shading in 3D plots', 'MNE_3D_OPTION_THEME': 'str, the color theme (light or dark) to use for 3D plots', 'MNE_BROWSE_RAW_SIZE': 'tuple, width and height of the raw browser window (in inches)', 'MNE_BROWSER_BACKEND': 'str, the backend to use for the raw browser ("qt" or "matplotlib")', 'MNE_BROWSER_OVERVIEW_MODE': 'str, the overview mode to use in the raw browser (see mne.viz.plot_raw() for valid options)', 'MNE_BROWSER_PRECOMPUTE': 'bool, whether to precompute raw data in the raw browser', 'MNE_BROWSER_THEME': 'str, the color theme (light or dark) to use for the raw browser', 'MNE_BROWSER_USE_OPENGL': 'bool, whether to use OpenGL for rendering in the raw browser', 'MNE_CACHE_DIR': 'str, path to the temporary and managed cache directory', 'MNE_COREG_ADVANCED_RENDERING': 'bool, whether to use advanced OpenGL rendering in coreg', 'MNE_COREG_COPY_ANNOT': 'bool, whether to copy the annotation files during warping', 'MNE_COREG_FULLSCREEN': 'bool, whether to use full-screen mode in coreg', 'MNE_COREG_GUESS_MRI_SUBJECT': 'bool, whether to guess the MRI subject in coreg', 'MNE_COREG_HEAD_HIGH_RES': 'bool, whether to use high-res head surface in coreg', 'MNE_COREG_HEAD_OPACITY': 'bool, the head surface opacity to use in coreg', 'MNE_COREG_HEAD_INSIDE': 'bool, whether to add an opaque inner scalp head surface to help occlude points behind the head in coreg', 'MNE_COREG_INTERACTION': 'str, interaction style in coreg (trackball or terrain)', 'MNE_COREG_MARK_INSIDE': 'bool, whether to mark points inside the head surface in coreg', 'MNE_COREG_PREPARE_BEM': 'bool, whether to prepare the BEM solution after warping in coreg', 'MNE_COREG_ORIENT_TO_SURFACE': 'bool, whether to orient the digitization markers to the head surface in coreg', 'MNE_COREG_SCALE_LABELS': 'bool, whether to scale the MRI labels during warping in coreg', 'MNE_COREG_SCALE_BY_DISTANCE': 'bool, whether to scale the digitization markers by their distance from the scalp in coreg', 'MNE_COREG_SCENE_SCALE': 'float, the scale factor of the 3D scene in coreg (default 0.16)', 'MNE_COREG_WINDOW_HEIGHT': 'int, window height for coreg', 'MNE_COREG_WINDOW_WIDTH': 'int, window width for coreg', 'MNE_COREG_SUBJECTS_DIR': 'str, path to the subjects directory for coreg', 'MNE_CUDA_DEVICE': 'int, CUDA device to use for GPU processing', 'MNE_DATA': 'str, default data directory', 'MNE_DATASETS_BRAINSTORM_PATH': 'str, path for Brainstorm data', 'MNE_DATASETS_EEGBCI_PATH': 'str, path for EEGBCI data', 'MNE_DATASETS_EPILEPSY_ECOG_PATH': 'str, path for epilepsy_ecog data', 'MNE_DATASETS_HF_SEF_PATH': 'str, path for HF_SEF data', 'MNE_DATASETS_MEGSIM_PATH': 'str, path for MEGSIM data', 'MNE_DATASETS_MISC_PATH': 'str, path for misc data', 'MNE_DATASETS_MTRF_PATH': 'str, path for MTRF data', 'MNE_DATASETS_SAMPLE_PATH': 'str, path for sample data', 'MNE_DATASETS_SOMATO_PATH': 'str, path for somato data', 'MNE_DATASETS_MULTIMODAL_PATH': 'str, path for multimodal data', 'MNE_DATASETS_FNIRS_MOTOR_PATH': 'str, path for fnirs_motor data', 'MNE_DATASETS_OPM_PATH': 'str, path for OPM data', 'MNE_DATASETS_SPM_FACE_DATASETS_TESTS': 'str, path for spm_face data', 'MNE_DATASETS_SPM_FACE_PATH': 'str, path for spm_face data', 'MNE_DATASETS_TESTING_PATH': 'str, path for testing data', 'MNE_DATASETS_VISUAL_92_CATEGORIES_PATH': 'str, path for visual_92_categories data', 'MNE_DATASETS_KILOWORD_PATH': 'str, path for kiloword data', 'MNE_DATASETS_LITE_DATA_PATH': 'str, path for lite_data data', 'MNE_DATASETS_FIELDTRIP_CMC_PATH': 'str, path for fieldtrip_cmc data', 'MNE_DATASETS_PHANTOM_KIT_PATH': 'str, path for phantom_kit data', 'MNE_DATASETS_PHANTOM_4DBTI_PATH': 'str, path for phantom_4dbti data', 'MNE_DATASETS_PHANTOM_KERNEL_PATH': 'str, path for phantom_kernel data', 'MNE_DATASETS_LIMO_PATH': 'str, path for limo data', 'MNE_DATASETS_REFMEG_NOISE_PATH': 'str, path for refmeg_noise data', 'MNE_DATASETS_SSVEP_PATH': 'str, path for ssvep data', 'MNE_DATASETS_ERP_CORE_PATH': 'str, path for erp_core data', 'MNE_FORCE_SERIAL': 'bool, force serial rather than parallel execution', 'MNE_LOGGING_LEVEL': 'str or int, controls the level of verbosity of any function decorated with @verbose', 'MNE_MEMMAP_MIN_SIZE': 'str, threshold on the minimum size of arrays passed to the workers that triggers automated memory mapping, e.g., 1M or 0.5G', 'MNE_REPR_HTML': 'bool, represent some objects with rich HTML in a notebook environment', 'MNE_SKIP_NETWORK_TESTS': 'bool, used in a test decorator (@requires_good_network) to skip tests that include large downloads', 'MNE_SKIP_TESTING_DATASET_TESTS': 'bool, used in test decorators (@requires_spm_data, @requires_bstraw_data) to skip tests that require specific datasets', 'MNE_STIM_CHANNEL': 'str, the default channel name for mne.find_events()', 'MNE_TQDM': 'str, either "tqdm", "tqdm.auto", or "off". Controls presence/absence of progress bars', 'MNE_USE_CUDA': 'bool, use GPU for filtering/resampling', 'MNE_USE_NUMBA': 'bool, use Numba just-in-time compiler for some of our intensive computations', 'SUBJECTS_DIR': 'path-like, directory of freesurfer MRI files for each subject'}
所有配置键概览#
由于上面的字典可能不易阅读，这里再次列出它，按字母顺序排序并以表格形式显示（使用 pandas.DataFrame），以便你概览 MNE-Python 识别的所有配置键及其用途：
pd.set_option("display.max_rows", None)
pd.set_option("display.max_colwidth", None)
(
pd.DataFrame(sorted(mne.get_config(key="").items()), columns=["Key", "Description"])
.style.hide(axis="index")
.set_table_attributes('class="dataframe" style="width: 100%;"')
)
恢复我们在上面更改的 pandas 默认设置：
pd.reset_option("display.max_rows")
pd.reset_option("display.max_colwidth")
通过向 set_config() 传入任意键，可以添加不属于已识别列表的配置变量。不过这会触发警告，这在你想设置有效键却只是拼错时是一种很好的检查：
mne.set_config("MNEE_USE_CUUDAA", "false")
/home/circleci/project/tutorials/intro/50_configure_mne.py:108: RuntimeWarning: Setting non-standard config type: "MNEE_USE_CUUDAA"
mne.set_config("MNEE_USE_CUUDAA", "false")
Attempting to create new mne-python configuration file:
/home/circleci/.mne/temp/.mne/mne-python.json
Could not read the /home/circleci/.mne/temp/.mne/mne-python.json json file during the writing. Assuming it is empty. Got: Expecting value: line 1 column 1 (char 0)
让我们删除刚才创建的配置变量。要取消某个配置变量，请使用 set_config() 并传入 value=None。由于我们处理的仍是（就 MNE-Python 而言）未识别的键，因此仍会收到警告，但该键会被取消设置：
mne.set_config("MNEE_USE_CUUDAA", None)
assert "MNEE_USE_CUUDAA" not in mne.get_config("")
/home/circleci/project/tutorials/intro/50_configure_mne.py:116: RuntimeWarning: Setting non-standard config type: "MNEE_USE_CUUDAA"
mne.set_config("MNEE_USE_CUUDAA", None)
配置的存储位置#
MNE-Python 将配置变量存储在一个 JSON 文件中。默认情况下，在 Windows 上该文件位于 %USERPROFILE% \.mne\mne-python.json，在 Linux 或 macOS 上位于 $HOME /.mne/mne-python.json。你可以使用 mne.get_config_path() 获取配置文件的完整路径。
print(mne.get_config_path())
/home/circleci/.mne/temp/.mne/mne-python.json
不过，不建议直接编辑 .mne 目录中的文件；请使用上一节介绍的获取与设置函数。
如果出于某种原因想从其他位置加载配置，可以将 home_dir 参数传给 get_config_path()，指定包含你要加载的配置文件所在 .mne 目录的父目录。
使用环境变量#
为了与 MNE-C 兼容，MNE-Python 也会读写环境变量来指定配置。这通过读写 JSON 配置的同一组函数完成，并由 use_env 和 set_env 参数控制。默认情况下，get_config() 会先检查 os.environ，然后再检查 MNE-Python 的 JSON 文件；若要仅检查 JSON 文件，请使用 use_env=False。为演示这一点，下面使用一个并非 MNE-Python 专用的环境变量（因此它不在 JSON 配置文件中）：
# make sure it's not in the JSON file (no error means our assertion held):
assert mne.get_config("PATH", use_env=False) is None
# but it *is* in the environment:
print(mne.get_config("PATH"))
/home/circleci/python_env/bin:/home/circleci/.local/bin/:/home/circleci/.go_workspace/bin:/usr/local/go/bin:/opt/google/google-cloud-sdk/bin:/opt/circleci/.rbenv/shims:/opt/circleci/.rbenv/bin:/opt/circleci/.pyenv/shims:/opt/circleci/.pyenv/bin:/usr/local/apache-maven/bin:/home/circleci/.yarn/bin:/home/circleci/.config/yarn/global/node_modules/.bin:/home/circleci/bin:/home/circleci/.go_workspace/bin:/usr/local/go/bin:/opt/google/google-cloud-sdk/bin:/opt/circleci/.rbenv/shims:/opt/circleci/.rbenv/bin:/opt/circleci/.pyenv/shims:/opt/circleci/.pyenv/bin:/usr/local/apache-maven/bin:/home/circleci/.yarn/bin:/home/circleci/.config/yarn/global/node_modules/.bin:/opt/circleci/.nvm/versions/node/v24.15.0/bin:/home/circleci/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin:/usr/local/gradle-9.5.0/bin:/usr/local/gradle-9.5.0/bin
同样默认情况下，set_config() 会同时在 JSON 文件和 os.environ 中设置值；若仅在 JSON 文件中设置配置变量，请使用 set_env=False。这里我们将使用 print() 语句来确认环境变量正在被创建和删除（我们也可以改用 Python 的 assert 语句，但它在成功时不打印任何输出，因此不太直观）：
mne.set_config("foo", "bar", set_env=False)
print("foo" in os.environ.keys())
mne.set_config("foo", "bar")
print("foo" in os.environ.keys())
mne.set_config("foo", None) # unsetting a key deletes var from environment
print("foo" in os.environ.keys())
/home/circleci/project/tutorials/intro/50_configure_mne.py:167: RuntimeWarning: Setting non-standard config type: "foo"
mne.set_config("foo", "bar", set_env=False)
False
/home/circleci/project/tutorials/intro/50_configure_mne.py:169: RuntimeWarning: Setting non-standard config type: "foo"
mne.set_config("foo", "bar")
True
/home/circleci/project/tutorials/intro/50_configure_mne.py:171: RuntimeWarning: Setting non-standard config type: "foo"
mne.set_config("foo", None) # unsetting a key deletes var from environment
False
Logging#
一个重要的配置变量是 MNE_LOGGING_LEVEL。在整个模块中，MNE-Python 会生成消息来描述其在后台执行的操作。你如何设置 MNE_LOGGING_LEVEL 决定了你会看到多少这类消息。全新安装 MNE-Python 时的默认日志级别是 info。
可以设置为配置变量的日志级别有 debug、info、warning、error 和 critical。MNE-Python 中约 90% 的日志消息是 info 消息，因此对大多数用户而言，选择在于 info（告诉我正在发生什么）和 warning（仅在出现令人担忧的情况时告诉我）之间。debug 日志级别面向 MNE-Python 开发者。
在前面的小节中，我们看到了如何使用 mne.set_config() 更改当前及以后所有 Python 会话的日志级别。若只想更改当前 Python 会话的日志级别，可以改用 mne.set_log_level()。该函数接受与 MNE_LOGGING_LEVEL 配置变量相同的五个字符串选项；此外，它还可以接受与这些字符串等价的 int 或 bool 值。对应关系见下表：
String |
Integer |
Boolean |
|---|---|---|
DEBUG |
10 |
|
INFO |
20 |
True |
WARNING |
30 |
False |
ERROR |
40 |
|
CRITICAL |
50 |
对于许多 MNE-Python 函数，可以通过 verbose 参数临时更改仅该函数调用的日志级别。为说明这一点，我们将在设置不同日志级别的情况下加载一些示例数据。首先，使用日志级别 warning：
kit_data_path = os.path.join(
os.path.abspath(os.path.dirname(mne.__file__)),
"io",
"kit",
"tests",
"data",
"test.sqd",
)
raw = mne.io.read_raw_kit(kit_data_path, verbose="warning")
没有生成任何消息，因为所有消息的严重程度都未达到“warning”或更严重。接下来，我们将以日志级别 info（默认级别）加载同一个文件：
raw = mne.io.read_raw_kit(kit_data_path, verbose="info")
Extracting SQD Parameters from /home/circleci/project/mne/io/kit/tests/data/test.sqd...
Creating Raw.info structure...
Setting channel info structure...
Creating Info structure...
Ready.
这一次，我们得到了一些关于从文件中提取信息、将该信息转换为 MNE-Python Info 格式等的消息。最后，如果我们请求 debug 级别的信息，会得到更多细节——而且这次我们使用 mne.use_log_level() 上下文管理器，这是实现与传入 verbose='debug' 相同效果的另一种方式：
with mne.use_log_level("debug"):
raw = mne.io.read_raw_kit(kit_data_path)
Extracting SQD Parameters from /home/circleci/project/mne/io/kit/tests/data/test.sqd...
Creating Raw.info structure...
KIT dir entry 0 @ 16
KIT dir entry 1 @ 32
KIT dir entry 2 @ 48
KIT dir entry 3 @ 64
KIT dir entry 4 @ 80
KIT dir entry 5 @ 96
KIT dir entry 6 @ 112
KIT dir entry 7 @ 128
KIT dir entry 8 @ 144
KIT dir entry 9 @ 160
KIT dir entry 10 @ 176
KIT dir entry 11 @ 192
KIT dir entry 12 @ 208
KIT dir entry 13 @ 224
KIT dir entry 14 @ 240
KIT dir entry 15 @ 256
KIT dir entry 16 @ 272
KIT dir entry 17 @ 288
KIT dir entry 18 @ 304
KIT dir entry 19 @ 320
KIT dir entry 20 @ 336
KIT dir entry 21 @ 352
KIT dir entry 22 @ 368
KIT dir entry 23 @ 384
KIT dir entry 24 @ 400
KIT dir entry 25 @ 416
KIT dir entry 26 @ 432
KIT dir entry 27 @ 448
KIT dir entry 28 @ 464
KIT dir entry 29 @ 480
KIT dir entry 30 @ 496
SQD file basic information:
Meg160 version = V2R004
System ID = 34
System name = NYU 160ch System since Jan24 2009
Model name = EQ1160C
Channel count = 192
Comment =
Dewar style = 2
FLL type = 10
Trigger type = 21
A/D board type = 12
ADC range = +/-5.0[V]
ADC allocate = 16[bit]
ADC bit = 12[bit]
Setting channel info structure...
Creating Info structure...
Ready.
我们一直向 verbose 参数传递字符串值，但从上表可以看出，verbose=True 会提供 info 消息，而 verbose=False 会抑制这些消息；这是脚本中很有用的简写方式，这样就不必记住不同日志级别的具体名称。最后一点：verbose=None（对于带有 verbose 参数的函数来说这是默认值）会回退到最近由 mne.set_log_level() 设置的日志级别；如果当前 Python 会话中尚未调用过该函数，则会回退到 mne.get_config('MNE_LOGGING_LEVEL') 的值。
获取系统信息#
你还可以获取有关 mne 从你的系统中导入了哪些依赖项的信息。可以通过以下命令行完成：
$ mne sys_info
或者，你可以直接使用 mne.sys_info()，它默认打印到 stdout：
Platform Linux-7.0.0-1004-aws-x86_64-with-glibc2.43 (X11)
Python 3.14.4 (main, May 12 2026, 13:57:53) [GCC 15.2.0]
Executable /home/circleci/python_env/bin/python
CPU AMD EPYC 9R45 (4 cores)
Memory 15.3 GiB
Core
├☑ mne 1.13.2 (latest release)
├☑ numpy 2.5.3 (OpenBLAS 0.3.34.106.0 with 1 thread via pthreads)
├☑ scipy 1.18.1
└☑ matplotlib 3.11.2 (backend=agg)
Numerical (optional)
├☑ scikit-learn 1.9.1
├☑ threadpoolctl 3.7.0
├☑ numba 0.67.0
├☑ nibabel 5.4.2
├☑ nilearn 0.14.1
├☑ dipy 1.12.1
├☑ openmeeg 2.5.16
├☑ jamica 0.3.0
├☑ pandas 2.3.3
├☑ h5io 0.2.5
├☑ h5py 3.16.0
└☐ unavailable python-picard, cupy
Visualization (optional)
├☑ pyvista 0.49.0 (OpenGL 4.5 (Core Profile) Mesa 26.0.8-1ubuntu0.3 via llvmpipe (LLVM 21.1.8, 256 bits))
├☑ pyvistaqt 0.13.1
├☑ vtk 9.7.0
├☑ qtpy 2.4.3 (PySide6=6.11.2)
├☑ ipympl 0.10.0
├☑ pyqtgraph 0.14.0
├☑ mne-qt-browser 0.8.0.dev43+gfe5898d2
├☑ ipywidgets 8.1.9
├☑ trame 3.13.2
├☑ trame_client 3.13.2
├☑ trame_server 3.12.5
├☑ trame_pyvista 0.1.7
├☑ trame_vtk 2.11.16
└☑ trame_vuetify 3.2.5
Ecosystem (optional)
├☑ mne-bids 0.20.0.dev44+g4728e50f3
├☑ mne-nirs 0.7.3
├☑ mne-features 0.3.2
├☑ mne-connectivity 0.9.0
├☑ mne-icalabel 0.9.0
├☑ mne-bids-pipeline 1.10.1
├☑ autoreject 0.5.1
├☑ neo 0.14.5
├☑ eeglabio 0.1.4
├☑ edfio 0.4.17
├☑ curryreader 0.1.2
├☑ mffpy 0.11.0
├☑ pybv 0.8.1
├☑ pymef 1.4.8
├☑ antio 0.7.1
└☑ defusedxml 0.7.1