做数据分析或者日常画图表的朋友，应该都遇到过“图表很漂亮，但代码一跑就报错”的尴尬。Plotly这个库我一直很喜欢，它的交互式图表是真的能拖能缩放，比matplotlib那种静态图生动太多了。但很多新手刚接触时，第一步就卡在安装上，比如pip install plotly明明提示成功，import却报模块不存在；或者plotly装好了，在Jupyter里就是不显示图形；再或者版本装错，连express子模块都找不到。这篇安装指南就是用来解决这些破事的。我会从环境准备讲起，把pip安装、conda安装、源码安装、离线安装都过一遍，再把不同编辑器里装plotly的姿势和常见报错也整理出来，适合所有刚接触Plotly的人照着操作，也适合已经踩过坑的人对照排查。

1. 安装前的准备与整体思路

很多人一上来就执行pip install plotly，装完发现各种问题，根源不是命令不对，而是没搞清楚自己当前环境的情况。安装本身确实只有几步，但前提是知道自己在干什么。

1.1 先确认Python和pip的底细

无论你用哪种方式装Plotly，第一步一定是确认Python环境。打开终端（Windows用CMD或PowerShell，macOS/Linux用终端），输入：

python --version pip --version

这两个命令会告诉你当前默认的Python版本和pip版本。这里有几个经常会混淆的情况：

• 如果你电脑里装了多个Python版本，比如同时装了Python 3.8和3.11，那么python和pip可能指向的是同一个版本，也可能不是同一个。
• 如果你在用Anaconda，你的终端里应该优先激活conda基础环境，再用python -m pip而不是直接用pip，否则可能装到别的环境里去。
• Windows下如果提示“python不是内部或外部命令”，说明Python没加进环境变量，先解决这个问题再继续。

检查pip到底属于哪个Python环境，最稳妥的方式是：

python -m pip --version

如果python命令本身绑定对了环境，这条命令的输出会明确显示pip所在的路径，例如C:\Python311\lib\site-packages，这个路径就能看出到底装在哪。

Plotly对Python版本的要求不算苛刻，Python 3.7以上基本都能跑，官方也一直在适配新版。真要说建议，我推荐用Python 3.9以上的版本，因为稍微新一点的功能和子模块在不同版本间兼容性更好，尤其是Plotly express，在老版本上偶尔会有些小脾气。

1.2 三种主流安装方式怎么选

Plotly的安装方式主要有三种，我在实际项目里都用过，适用场景差别挺大。

第一种是pip安装，这是最通用、也最适合大多数人的方式。pip会从PyPI下载wheel包，自动处理依赖关系，一条命令搞定。

第二种是conda安装，适合用Anaconda管理Python环境的人。conda的优点是自带了很多二进制依赖，而且对环境隔离做得好，不会跟系统其他项目冲突。

第三种是源码安装，适合想尝鲜开发版或者研究Plotly内部实现的极客。从GitHub拉源码然后本地构建，正常情况下没必要，但如果你想修复某个自己遇到的bug，或者想用还没发布的开发版特性，可以用这种。

在后面的正文里，我会把每种方式的具体操作和适用场景展开讲清楚。简单来说，我个人的习惯是：日常快速用就pip，在conda环境里折腾就conda，追新特性才去碰源码。

1.3 版本选择背后的逻辑

很多新手会问，为什么不直接装最新版？这个问题问得好。Plotly本身更新迭代很快，新版虽然功能更多，但可能需要更高版本的依赖包，比如pandas、numpy、nbformat等。如果你的项目中有一些老旧代码依赖的是旧版pandas，强制升级plotly就可能导致其他库崩溃。

所以真正合理的选择逻辑是这样的：

• 全新项目，没有任何历史包袱：直接装最新版。
• 项目已有依赖，不想影响其他包：指定一个和现有环境兼容的版本，比如pip install plotly==5.18.0。
• 只需要基础画图功能，不涉及交互组件更新：可以装5.14.x这种稳定版本，没必要追新。

还有一个点，Plotly有很多个子模块，比如plotly.express（简化画图接口）、plotly.graph_objects（底层绘图接口）、plotly.subplots（子图工具）等。这些都在同一个plotly包里，不需要单独安装。很多人误以为plotly.express缺了就再装一个express包，这是不对的，它只是Plotly自带的一个模块。

2. Plotly核心库的完整安装步骤

搞清楚环境后，就可以开始装了。这一章我会把几种安装方式都写出来，每一条命令都解释清楚它到底做了什么，以及你可能遇到的坑。

2.1 用pip安装Plotly的标准流程

先给一个最通用、最不会出错的方案：

python -m pip install --upgrade pip

为什么要先升级pip？因为旧版本的pip经常解析不了新wheel包的一些标记，导致安装失败或者把依赖解析得乱七八糟。这一步在我的经验里能解决大量莫名其妙的安装错误。

接着执行核心安装：

python -m pip install plotly

如果用pip install plotly不行，那多半是环境变量或者多Python环境的问题，用python -m pip的形式可以绕开命令解析的坑。

安装过程会看到类似“Collecting plotly”、“Downloading plotly-5.x.x-py2.py3-none-any.whl”这样的输出，这个wheel包是Python 2和Python 3通用的，所以不用担心版本号里有“py2.py3”会不会装错问题。

装完后如果还想装pandas（Plotly express绘图时经常要用DataFrame），一并装掉：

python -m pip install pandas

2.2 用conda安装Plotly

Anaconda用户更建议用conda。打开Anaconda Prompt，或者激活conda环境后输入：

conda install -c plotly plotly

这行命令的意思是：从plotly官方channel安装plotly包。-c plotly指定的是channel来源，如果不加，conda默认从conda-forge找，通常也能装到，但版本可能不是最新的。如果想安装最新版，建议用plotly官方的channel。

有些教程会让你先执行conda install -c plotly plotly-orca，那是用于静态图导出的，不是核心库，装不装取决于你是否需要把图导出为png。后面我会专门讲orca和kaleido。

conda的好处是能自动处理很多底层依赖，比如numpy、pandas等，它不会粗暴地升级你的包导致冲突。如果你的conda环境比较乱，用conda安装比pip更稳。

2.3 安装配套组件：pandas、kaleido、ipywidgets

Plotly的核心包只是一个绘图引擎，真正要用得顺手，还需要搭配几个组件。很多人只装了plotly，结果画不了图或者导出不了图片，就是少了这几个东西。

pandas：Plotly express绘制数据图表时，常用DataFrame作为数据源，装了pandas才能顺利做数据筛选、聚合等操作。

kaleido：如果你想用fig.write_image("chart.png")把图表导出为静态图片，就需要这个库。安装方式：

python -m pip install kaleido

kaleido本质是一个跨平台的图形渲染引擎，装的时候会下载对应操作系统的二进制文件，所以体积比较大，下载慢是正常的。还有一点要注意，kaleido在某些服务器环境（比如缺少系统库的Linux）下可能会报错，后面的排查部分我会给对策。

ipywidgets：如果你在Jupyter Notebook里用Plotly，需要它来显示交互控件。安装方式：

python -m pip install ipywidgets

装完后建议重启Jupyter内核，并执行一次widgets扩展的启用命令：

jupyter nbextension enable --py widgetsnbextension

这一步不执行，后面在Notebook里可能会看到图表无法渲染或控件不响应的情况。

2.4 源码安装与指定版本安装

追新版本或者想改源码时，源码安装才有意义。操作步骤也不多：

git clone https://github.com/plotly/plotly.py.git cd plotly.py python -m pip install -e .

-e选项是editable模式，意思是你对源码做的改动会立即生效，不用重新安装。这样做的好处是方便调试，但坏处是如果源码有bug，你可能连基础功能都用不了。所以我只建议在研究源码、写扩展插件时用这种模式。

指定版本安装则适合需要固定版本号的场景：

python -m pip install plotly==5.18.0

或者指定一个最低版本，避免旧版：

python -m pip install "plotly>=5.14,<6"

这个范围写法也很有用，它会安装5.x里最新的兼容版本，同时又不会越级跳到6.x去搞乱你的代码。

3. 不同开发环境下的安装与集成

同样一个plotly，在PyCharm、Jupyter Notebook、VS Code里安装和使用，体验差别是相当大的。这一章专门把不同环境的坑列出来。

3.1 PyCharm里装Plotly的注意事项

PyCharm这个IDE比较特殊，它会给项目创建虚拟环境。如果你直接在PyCharm的Terminal里敲pip install plotly，很可能装到了全局Python环境，而不是当前项目里，然后在代码里import就报错。

正确做法有两种：

第一种，在PyCharm的设置里添加包：打开File -> Settings -> Project -> Python Interpreter，点左边的“+”号，搜索plotly，选中后点Install Package。这种方式PYCharm会直接把包装进当前项目解释器，不会跑偏。

第二种，在PyCharm的Terminal里用项目解释器对应的pip安装：

python -m pip install plotly

记住，务必确保Terminal里激活的是项目对应的虚拟环境。如果Terminal提示符前面出现了(venv)字样，说明虚拟环境已经激活，此刻安装就是装到项目里的。

很多人在PyCharm里遇到的另一个问题是，Terminal里的Python版本跟Settings里显示的解释器版本不一样。这是因为PyCharm的Terminal默认使用的shell可能绑定了另一个Python。这时你需要看Settings里项目的解释器路径，然后在Terminal里手动指定：

C:/Users/你的用户名/项目目录/venv/Scripts/python.exe -m pip install plotly

虽然麻烦一点，但能保证装对位置。经验之谈，大部分人在PyCharm里遇到的“找不到plotly”问题，不是没装，而是装错了地方。

3.2 Jupyter Notebook与VS Code的安装细节

Jupyter Notebook使用Plotly，核心问题是渲染器的配置。装好plotly和ipywidgets并按前面说的启用了widgets扩展之后，在Notebook里正常绘图就没什么问题了。如果发现图表没有显示，而是输出了一段JSON文本，说明渲染器没配对。

在Notebook顶部加上这段代码强制指定渲染器：

import plotly.io as pio pio.renderers.default = "notebook"

可选的值有：

• notebook：在Jupyter Notebook里内嵌显示。
• browser：在默认浏览器新标签页打开交互图表。
• png：直接渲染成静态图片。
• jupyterlab：JupyterLab里用。

VS Code本身不像PyCharm那样强制虚拟环境，但它的Python扩展会选择一个解释器。切换解释器的方式是：按下Ctrl+Shift+P，输入“Python: Select Interpreter”，选择项目对应的虚拟环境。装plotly后如果import不到，先检查这里是不是选对了解释器。VS Code的Jupyter插件也支持直接跑Notebook，渲染器配置和Jupyter Notebook里一样，同样需要设置renderers.default。

3.3 离线环境与内网环境的安装方案

有些公司内网服务器无法直连外网，这时候常规pip install plotly就没戏了。我在离线部署时常用的方案是：在一台能联网的机器上下载好所有依赖包，再拷贝到内网机器上离线安装。

第一步，在能联网的机器上执行：

mkdir plotly_packages cd plotly_packages python -m pip download plotly -d .

pip download不仅会下载plotly，还会下载它的所有依赖，比如tenacity、packaging、numpy等。下载完成后，把这些文件打包拷到离线机器上，然后在离线机器上执行：

python -m pip install --no-index --find-links=./plotly_packages plotly

--no-index的意思是不要从PyPI拉取，只用本地文件夹里的包。这么做的好处是稳定可控，坏处是需要手动处理依赖层级，每次有新项目都要重新准备一份完整的下载包。

还有一个常见坑是，离线环境如果需要kaleido，一定要检查它有没有对应的系统库依赖。像在精简版Linux容器里，kaleido可能跑不起来，这时候静态图导出会失败，更稳妥的方案是改用服务器端截图服务或者在浏览器里手动导出。

4. 安装后的验证与快速自检

包装完了不代表万事大吉，一定要跑一遍完整的自检流程。很多问题在真正使用的时候才暴露，这时候再排查就费事了。安装后花三分钟验证一下，能省掉后面一小时的抓狂。

4.1 三步验证安装是否成功

第一步，检查包是否存在：

python -m pip show plotly

如果正常安装，会输出包含Version、Location、Requires等字段的信息。如果提示“WARNING: Package(s) not found”，说明根本没装上。

第二步，验证能否正常导入：

python -c "import plotly; print(plotly.__version__)"

能输出版本号，基本就可以确认plotly的核心库已经就位了。

第三步，跑一个最小绘图测试。在终端执行：

python -c "import plotly.express as px; fig = px.scatter(x=[1,2,3], y=[3,2,1]); print(fig.to_json()[:200])"

这段代码会创建一个最简单的散点图并输出它的JSON结构，如果没有报错，就说明Plotly的引擎能正常构建图表对象。

我在实际项目里通常会把这三步做成一个脚本，一键执行，快速定位环境问题。新手朋友也建议跑一遍，特别是第三步，它验证的是整个绘图链路，而不仅仅是包的导入。

4.2 渲染器和输出格式的验证

除了基本的包导入，我们还要验证图表能不能显示、能不能导出。这两件事最容易出幺蛾子。

先验证在脚本环境下能正常渲染。创建一个test.py文件：

import plotly.express as px fig = px.bar(x=["a", "b", "c"], y=[1, 3, 2]) fig.write_html("test.html") print("HTML saved")

运行python test.py，如果同目录下生成了test.html文件，说明Plotly的HTML渲染链路是通的。然后用浏览器打开这个文件，能看到交互图表就说明一切正常。

再验证静态图片导出：

import plotly.express as px fig = px.bar(x=["a", "b", "c"], y=[1, 3, 2]) fig.write_image("test.png") print("PNG saved")

如果这里报了kaleido相关的错误，说明静态导出依赖没装好。根据我之前的经验，fig.write_image这个接口在kaleido正常的情况下，几秒钟就能出图，如果长时间卡住，十有八九是kaleido的系统依赖问题。

4.3 排除旧版本缓存带来的干扰

安装新版本后，有时import的还是旧版本。这种情况我遇到好几次，尤其在Jupyter或PyCharm里。原因是Python的包缓存机制或Notebook内核还在使用旧的内核状态。

处理办法是先看版本号：

python -c "import plotly; print(plotly.__version__)"

如果显示的版本不是刚刚安装的新版本，说明包查找路径里混入了旧包。可以先卸载再安装：

python -m pip uninstall plotly python -m pip install --no-cache-dir plotly

--no-cache-dir参数会强制pip不使用本地缓存，直接去下载一个新的wheel包，能有效避免缓存里残留旧版本的问题。Notebook里如果还不行，记得重启内核（Kernel -> Restart），让它重新加载所有模块。

5. 常见安装问题排查与实用技巧

再顺利的安装，也总有人会撞上各种奇奇怪怪的报错。这一章我按问题类型整理了一份排查表和几个我压箱底的技巧，希望你能少走弯路。

5.1 高频问题速查表

这份表是我实际操作中遇到频率最高的几类问题，建议收藏，装的时候对照着排查。

5.2 网络慢和超时的处理

国内用户装plotly时，最头疼的问题就是网络。PyPI的默认源在国外，下载速度时快时慢，超时更是家常便饭。解决思路有三个：

第一个，换国内镜像源。以清华源为例：

python -m pip install plotly -i https://pypi.tuna.tsinghua.edu.cn/simple

我用的比较多的是清华源和阿里云源。一次性的镜像源参数可以解决单次安装问题，也可以设置默认源：

python -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

设置好之后，后续所有pip安装都会默认走这个镜像，速度会明显提升。

第二个，增加超时时间。有些网络环境虽然能连通，但速度极慢，pip默认15秒超时是肯定不够的。可以设置更长的超时：

python -m pip install --timeout 120 plotly

第三个，用断点续传或重试。pip自身支持重试机制，如果中途失败可以加--retries 5参数，重试次数增加能提高成功率。下载大体积包时这个参数特别有用。

5.3 版本冲突的处理策略

版本冲突是安装完plotly后跑其他代码时经常遇到的雷。常见场景是这样的：项目里已有的依赖要求numpy<1.25，而Plotly新版本则倾向于搭配较新的numpy，pip在安装时可能会自动升级numpy，结果其他代码就崩了。

处理策略有两个方向。一是装一个已知与当前环境兼容的plotly版本，用--no-deps参数跳过依赖自动升级，然后手动安装合适的依赖：

python -m pip install --no-deps plotly==5.18.0

这会让pip安装plotly时不碰任何其他包。前提是你确认当前环境已有的依赖已经满足plotly的基本要求，比如tenacity、packaging、numpy等。

二是创建独立的虚拟环境，从源头上阻断冲突。比如用venv：

python -m venv plotly_env

Windows下激活：

plotly_env\Scripts\activate

macOS/Linux下激活：

source plotly_env/bin/activate

然后在这个环境里随便装plotly，完全不影响全局环境。这个方法适合做数据分析或者实验性项目，一套干净的环境能省去很多麻烦。

5.4 多Python环境混用的避坑指南

多Python环境是新手最容易翻车的场景。我自己也踩过坑：电脑里既有Anaconda的Python，又有从官网装的Python，还有PyCharm创建的venv，一个不留神就把包装到了错误的地方。

避免这种混乱的黄金规则是：所有与Python包相关的操作，都通过python -m pip而不是裸pip。因为python -m pip会明确使用当前python命令对应的环境，而裸pip则指向你PATH里最靠前的那个pip，两者可能不一样。

如果你想彻底搞清楚当前环境里有没有plotly，可以用：

python -c "import sys; print(sys.executable)" python -c "import plotly; print(plotly.__file__)"

第一条命令会显示当前Python解释器的完整路径，第二条会显示plotly包的位置。如果两者不在同一个虚拟环境目录下，就说明你的import路径有问题。

在Anaconda里，最稳妥的方式是创建独立conda环境再安装：

conda create -n plotly_env python=3.10 conda activate plotly_env conda install -c plotly plotly

conda环境的隔离性比venv更好，因为conda不仅管理Python包，还能管理一些底层库的版本，这对处理依赖冲突非常有帮助。

6. 装上Plotly之后还要做的几件事

安装只是起点，真正要让Plotly跑得顺，还需完成一些收尾配置。这一章讲的不是画图技巧，而是直接影响使用体验的细节，踩过坑的人应该能懂这里面有多少门道。

6.1 检查并安装jupyter相关的可选依赖

如果你主要在Jupyter Notebook或JupyterLab里工作，除核心的plotly外，有些可选依赖建议一并装上，它们能让图表在编辑器里直接交互显示，体验完全不同。

python -m pip install jupyterlab plotly ipywidgets

装完jupyterlab和plotly后，需要在JupyterLab里也启用一次plotly的扩展。相对较新的JupyterLab版本已经自带plotly渲染支持，但如果发现图表显示不出来，可以在终端执行：

jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget

然后重启JupyterLab。我的实际体验是，现代版本基本不需要手动装扩展，但偶尔升级JupyterLab后plotly会失灵，这个时候就要重新执行这条命令。

6.2 给Jupyter Notebook配置默认渲染器

除了命令行验证，我建议在Notebook里也固定一个渲染器设置，避免每次新开文件都要手动指定。可以在你的Jupyter配置文件，或者直接在代码里设置。

要知道渲染器到底是怎么回事，我用一个生活化的例子来说：渲染器决定了你的Plotly图表是“嵌在网页里”，还是“弹到新窗口”，或者是“烤成一张静态图”。默认情况下，Notebook里可能是browser或其他模式，所以如果你发现图表弹出浏览器而非显示在Notebook里，那就是渲染器设置的问题。

在.ipynb文件顶部加入：

import plotly.io as pio pio.renderers.default = "notebook"

如果你用的是JupyterLab，改成：

pio.renderers.default = "jupyterlab"

设置一次后，当前Notebook内的所有图表都会遵守这个渲染器设置，后续画图就省心了。

6.3 学会利用Plotly的离线模式与远程资源

Plotly虽然主要是在本地运行，但它的图表文件有时会引用CDN上的JavaScript资源，这意味着某些内网环境下，图表虽然生成了HTML，打开时却可能是空白页。

解决方案是使用Plotly的离线模式。具体来说，可以在生成HTML时使用：

import plotly.offline as pyo pyo.plot(fig, include_plotlyjs=True, filename="offline_plot.html")

include_plotlyjs=True会直接把Plotly的JavaScript代码嵌入到HTML文件里，这样即使没有外网，也能在浏览器里正常打开和交互。代价是HTML文件会稍微大一些，但不影响使用。在我做内网项目交付的时候，这个参数救过我好几次。

7. 写在最后的一点经验

和我一起装过环境的人都知道，Plotly的安装本身并不复杂，真正的拦路虎大多是环境混乱和依赖冲突。无论是坚持用python -m pip，还是善用venv和conda环境隔离，又或者是设置国内镜像源，归结起来，都是为了让你装包时少一些“为什么又是这个错”的挫败感。

我个人的习惯是：每次新项目，新建一个虚拟环境，先升级pip，再安装plotly和基础配套包，然后跑一遍自检脚本。这套流程虽然多花两三分钟，但能让我后续画图时把精力全部集中在数据本身，而不是折腾环境上。

如果你在安装过程中遇到了这篇文章没提到的问题，先别急，格式化地看一眼报错信息，通常它能告诉你80%的线索。实在不行，新建干净环境再来一次，往往比继续在当前乱环境里死磕更省时间。