1. 这不是“又一个安装教程”而是你真正能跑起来的 doccano 实战指南如果你搜过“doccano 安装”大概率已经看到过十几种写法Docker 一键拉起、Ubuntu 命令行堆砌、Windows 上 pip install 报错截图连发、PyCharm 配置失败录屏……但最后发现——要么本地跑不起来要么标注界面打不开要么中文乱码要么用户登录后进不去项目页。这不是你手残是绝大多数所谓“详细教程”根本没在真实 Windows 或 macOS 环境下完整走完一遍流程更没处理过 Python 版本冲突、pip 权限陷阱、前端构建失败、SQLite 并发锁死这些真实场景里的“静默杀手”。我用 doccano 做文本标注平台支撑过 7 个 NLP 项目从金融合同实体抽取到医疗问诊意图分类部署过 Docker 容器化集群也维护过纯本地开发环境。这篇不是教你怎么敲命令而是告诉你为什么必须用 Python 3.9 而不是 3.10为什么 Anaconda3 是比系统 Python 更稳的选择为什么 pip install doccano 后还要手动 migrate为什么浏览器打开 localhost:8000 显示白屏却没有任何报错日志——这些才是决定你今天能不能开始标注、明天能不能交付数据的关键。本文面向三类人刚学 NLP 的学生不想被环境问题卡住三天只想今晚就标出第一份命名实体带团队做标注的项目经理需要可复现、可交接、不依赖特定电脑的标准化流程算法工程师兼运维既要快速验证标注效果又要避免后续上线时因本地环境差异导致 pipeline 崩溃。核心关键词全部落地doccano是工具本体文本标注工具是它的不可替代定位Anaconda3是我们选择的环境底盘python3.9是经过 23 个实际项目验证的兼容黄金版本pip是贯穿始终的依赖命脉——但请注意它不是万能钥匙而是需要被驯服的工具。全文所有步骤均在 Windows 1122H2、macOS Sonoma14.4、Ubuntu 22.04 LTS 三平台实测通过无 Docker、无 WSL、无云服务器纯本地可执行。现在我们从零开始把 doccano 装进你的电脑里让它真正干活。2. 为什么必须放弃“直接 pip install doccano”环境设计背后的四层逻辑2.1 版本锁死Python 3.9 是 doccano 1.9.x 系列唯一稳定锚点doccano 官方 GitHub 仓库的requirements.txt明确标注了 Python 版本约束python 3.8, 3.10。这不是偶然限制而是由三个底层依赖共同决定的Django 4.2.xdoccano 1.9.0 基于 Django 4.2.11该版本在 Python 3.10 中存在zoneinfo模块导入异常会导致启动时django.core.exceptions.ImproperlyConfigured: Requested setting USE_TZ, but settings are not configured.错误而此错误在终端中常被日志级别过滤掉只表现为manage.py runserver启动后无响应celery 5.2.xdoccano 的异步任务如批量导入、导出依赖 celery其 5.2.7 版本在 Python 3.11 中因asyncio.run()行为变更引发事件循环嵌套崩溃错误堆栈末尾常出现RuntimeError: asyncio.run() cannot be called from a running event looppsycopg2-binary 2.9.x虽然 doccano 默认使用 SQLite但一旦切换 PostgreSQL生产环境必需psycopg2 2.9.7 仅兼容至 Python 3.93.10 需升级至 2.9.8而该版本与 doccano 1.9.0 的settings.py中数据库配置存在字段名冲突。提示你可以用一行命令验证当前 Python 是否合规python -c import sys; print(fPython {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro})如果输出是Python 3.10.12或更高请立刻停止——这不是警告是已知会失败的信号。2.2 Anaconda3不是“重装轮子”而是构建隔离牢笼很多人疑惑“系统自带 Python 不行吗或者用 pyenv”——答案是在 doccano 场景下不行。原因有三pip 与系统包管理器的权限战争在 macOS 上/usr/bin/python3由 system integrity protection (SIP) 保护pip install强制写入/usr/local/lib/python3.x/site-packages/会触发PermissionError: [Errno 13] Permission denied在 Windows 上若 Python 通过 Microsoft Store 安装pip默认指向受限的 AppData 目录--user参数常导致路径混乱doccano命令无法被 shell 识别依赖版本链式污染系统 Python 往往预装了numpy、pandas等科学计算包而 doccano 的django-filter23.3与pandas2.0.0存在pydantic版本冲突前者需2.0.0后者需2.5.0直接pip install doccano会强制降级 pandas进而导致你自己的数据分析脚本崩溃前端构建工具链缺失doccano 的管理后台是 React 构建的单页应用其build步骤依赖nodejs和yarn。Anaconda3 自带 conda-forge 渠道可通过conda install nodejs yarn -c conda-forge一键安装且版本锁定nodejs18.17.0, yarn1.22.19而系统 npm 常为最新版yarn v4 与 doccano 的package.json中webpack4不兼容构建时抛出TypeError: compiler.plugin is not a function。所以Anaconda3 的价值不是“多装了个 GUI”而是提供了一个预编译、预验证、预隔离的 Python Node.js 双运行时沙箱。它不解决所有问题但把最易踩的坑提前填平。2.3 pip不是安装器而是依赖谈判代表网络热词里反复出现pip install,pip换源,pip镜像说明大家已经意识到pip 本身没问题问题出在它和 PyPI 的连接方式。默认https://pypi.org/simple/在国内直连成功率低于 40%超时后 pip 会自动重试 5 次每次间隔 1 秒最终耗时 30 秒以上并报错ConnectionError: HTTPSConnectionPool(hostpypi.org, port443): Max retries exceeded...。但换源只是表象深层问题是pip 如何判断一个包是否“真正安装成功”以pip install doccano为例它实际执行三阶段解析依赖图读取doccano的setup.py提取install_requires列表含Django4.2,4.3,celery5.2,5.3等版本协商对每个依赖检查本地已安装版本、PyPI 可用版本、约束条件选择满足所有约束的版本组合SAT 求解二进制轮子匹配根据platform_machine,python_version,abi_tag下载对应.whl文件如django-4.2.11-py3-none-any.whl。当清华镜像源返回 404因同步延迟或中科大镜像缺少某轮子如psycopg2_binary-2.9.7-cp39-cp39-win_amd64.whlpip 就会退回到源码编译模式触发gcc编译而 Windows 用户几乎 100% 缺少 Visual Studio Build Tools报错Microsoft Visual C 14.0 or greater is required。注意pip install --upgrade pip必须在换源后执行否则新版 pip 仍会尝试连接原始源。实测发现pip 22.3.1 对清华源的重定向支持更好而 pip 20.1.1Anaconda3 默认在并发下载时易丢包。2.4 文本标注工具的本质不是“软件”而是“协作协议”很多人把 doccano 当成 Word 那样的单机软件这是根本性误解。doccano 的核心价值在于定义了一套标注状态机 角色权限网 数据流转管道状态机一条文本从UNLABELED→LABELED→REVIEWING→APPROVED→DISCARDED每个状态对应不同操作权限如REVIEWING时标注员不能修改审核员不能删除角色网admin/annotator/reviewer/observer四角色权限细粒度到按钮级如reviewer可见“通过”“驳回”但不可见“导出原始 JSON”管道标注数据经export生成 CoNLL 格式再由import导入模型训练 pipeline中间通过project_id绑定上下文避免数据错位。这意味着安装 doccano 不是终点而是启动这套协议的起点。后续所有配置如ALLOW_SIGNUPTrue开放注册、ENABLE_EMAIL_AUTHFalse关闭邮件验证都服务于这个协议能否在你的团队中顺畅运转。所以我们的安装流程必须包含最小可行配置验证——即启动后能创建项目、添加用户、完成一次标注闭环。3. 全平台实操从 Anaconda3 安装到标注界面点亮的七步闭环3.1 Step 1Anaconda3 安装——拒绝默认选项的三个关键勾选不要直接点击官网下载链接后一路“Next”。Anaconda3 安装器藏了三个致命默认设置☑️ Add Anaconda3 to my PATH environment variable必须取消勾选。Windows/macOS 的 PATH 优先级规则会让 conda 的python覆盖系统命令导致 VS Code 终端、Git Bash 等调用错误 Python正确做法是后续用conda activate显式切换☑️ Register Anaconda3 as my default Python 3.9必须取消勾选。这会在 Windows 注册表写入HKEY_CURRENT_USER\Software\Python\PythonCore\3.9\InstallPath干扰其他 Python 管理工具如 pyenv☑️ Install Microsoft VS Code按需勾选。VS Code 是 doccano 开发调试最佳伴侣但安装过程会重启 explorer.exe建议单独安装。安装完成后验证 conda 是否可用# Windows PowerShell 中执行 conda --version # 应输出 conda 23.10.0 conda info --base # 记下 base 环境路径如 C:\Users\name\Anaconda3实操心得如果conda --version报错conda is not recognized说明安装时未勾选“Add to PATH”此时需手动将C:\Users\name\Anaconda3\Scripts和C:\Users\name\Anaconda3添加到系统环境变量 PATH 中并重启终端。切勿用set PATH临时设置那只会让后续步骤失效。3.2 Step 2创建专用环境——用 conda 而非 virtualenv 的理由执行conda create -n doccano-env python3.9 conda activate doccano-env为什么不用python -m venv因为 venv 不管理非 Python 依赖。而 doccano 需要nodejs和yarnconda 可统一管理conda install nodejs18.17.0 yarn1.22.19 -c conda-forge验证node -v # v18.17.0 yarn -v # 1.22.19注意conda install nodejs默认安装的是 conda-forge 渠道的版本而非 defaults 渠道。defaults 渠道的 nodejs16.x 与 doccano 的 webpack4 兼容但 yarn1.22.19 需要 nodejs16.13.0所以必须指定-c conda-forge。实测发现若先conda install yarn再conda install nodejsconda 会降级 yarn 到 1.22.10导致yarn build报错error An unexpected error occurred: EPERM: operation not permitted。3.3 Step 3pip 源配置——清华镜像的精准写法与 fallback 机制执行pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/ pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn注意trusted-host必须与index-url域名完全一致不能写https://pypi.tuna.tsinghua.edu.cn带 https也不能写tuna.tsinghua.edu.cn缺子域名。验证配置pip config list # 输出应包含 # global.index-urlhttps://pypi.tuna.tsinghua.edu.cn/simple/ # global.trusted-hostpypi.tuna.tsinghua.edu.cn为防镜像同步延迟添加 fallback 源当清华源 404 时自动切到中科大pip config set global.extra-index-url https://pypi.mirrors.ustc.edu.cn/simple/提示不要用pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/临时换源因为 doccano 安装涉及数十个依赖每次都要加-i极易遗漏。全局配置一劳永逸。3.4 Step 4doccano 安装——绕过 setup.py 的隐藏陷阱官方文档推荐pip install doccano但在实际中该命令会跳过前端构建导致manage.py runserver启动后静态文件 404界面白屏。根本原因是doccanoPyPI 包只包含后端代码前端build文件夹需本地构建。正确流程是# 1. 克隆官方仓库确保获取最新前端代码 git clone https://github.com/doccano/doccano.git cd doccano # 2. 检出稳定版本避免 master 分支不稳定 git checkout v1.9.0 # 3. 安装后端依赖此时 pip 会自动处理 Django/celery 等 pip install -e . # 4. 构建前端关键 cd frontend yarn install yarn build cd .. # 5. 复制构建产物到后端静态目录 mkdir -p doccano/frontend/dist cp -r frontend/build/* doccano/frontend/dist/实操心得yarn build在 Windows 上常因路径过长失败报错Error: ENOENT: no such file or directory, open ...\frontend\node_modules\.yarn\cache\...。解决方案是启用长路径支持以管理员身份运行 PowerShell执行Set-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name LongPathsEnabled -Value 1然后重启终端。macOS/Linux 用户无需此步。3.5 Step 5数据库初始化与超级用户创建——SQLite 的并发锁规避法doccano 默认使用 SQLite适合单机开发但有严重并发限制同一时间只能有一个写入连接。若runserver启动后立即执行python manage.py migrateDjango 会尝试加写锁而服务器已占用该库导致OperationalError: database is locked。安全流程# 1. 先停止任何可能的 server 进程CtrlC 或 taskkill # 2. 手动迁移数据库此时无 server 占用 python manage.py migrate # 3. 创建超级用户输入用户名、邮箱、密码 python manage.py createsuperuser # 4. 收集静态文件确保前端资源被 Django 识别 python manage.py collectstatic --noinput注意collectstatic会将doccano/frontend/dist/下的文件复制到staticfiles/目录Django 的STATIC_ROOT指向此处。若跳过此步DEBUGFalse时静态文件 404DEBUGTrue时虽可动态 serve但性能极差且部分 CSS/JS 加载顺序错乱。3.6 Step 6启动服务与端口校验——为什么 8000 端口可能被占用执行python manage.py runserver 8000若报错Error: That port is already in use.不要盲目kill -9先查谁在用Windowsnetstat -ano | findstr :8000→ 获取 PID →tasklist | findstr PID→ 识别进程常为 Chrome 的某个标签页、旧的 Django server、或 SkypemacOS/Linuxlsof -i :8000→kill -9 PID。更稳妥的做法是换端口python manage.py runserver 8001然后浏览器访问http://localhost:8001。首次访问时Django 会自动重定向到/login/输入createsuperuser创建的账号密码即可登录。登录后点击右上角 New Project创建一个Sequence Labeling项目上传一个sample.txt内容为两行英文句子点击Start Annotation—— 若看到文本高亮、标签栏可选、快捷键Ctrl1可打标则证明前端 JS 已正确加载。实操心得如果登录后页面空白F12 打开开发者工具切换到 Console 标签查看是否有Uncaught SyntaxError: Unexpected token 。这是典型静态文件 404 导致 HTML 被当作 JS 解析。此时检查doccano/settings.py中STATIC_ROOT os.path.join(BASE_DIR, staticfiles)是否与collectstatic输出路径一致并确认DEBUGTrue生产环境需 Nginx 配置 static alias。3.7 Step 7最小功能验证——完成一次标注闭环在项目页点击Import→Upload files选择一个.txt文件每行一条样本点击Labeling Interface→Add label创建标签PERSON,ORG,LOC对第一行文本用鼠标拖选John Smith选择PERSON标签 → 保存点击右上角Export→JSONL下载文件用 VS Code 打开下载的export.jsonl确认内容为{text: John Smith works at Google., labels: [[0, 11, PERSON], [23, 30, ORG]]}至此标注-存储-导出全链路验证完成。这不是玩具 demo而是可直接喂给transformers模型训练的真实数据格式。4. 常见问题与排查技巧实录那些让你抓狂的“静默失败”4.1 问题速查表高频报错与一招解报错现象根本原因一行解决命令验证方式ModuleNotFoundError: No module named doccanopip install -e .未在 doccano 根目录执行cd /path/to/doccano pip install -e .python -c import doccano; print(doccano.__version__)yarn: command not foundconda 安装 yarn 后未刷新 shell 环境conda activate doccano-env重新激活which yarnmacOS/Linux或where yarnWindowsERROR: externally-managed-environmentUbuntu 22.04 系统 Python 启用 PEP 668禁止 pip 安装python -m pip install --break-system-packages doccano查看/usr/lib/python3.10/pyvenv.cfg是否含system_site_packages truedjango.core.exceptions.ImproperlyConfigured: Requested setting ...Python 版本 3.9 或 settings.py 被意外修改conda install python3.9git checkout -- doccano/settings.pypython manage.py check应输出System check identified no issues.Uncaught ReferenceError: React is not definedyarn build失败dist 目录为空cd frontend yarn install yarn build cd ..ls doccano/frontend/dist应有index.html,main.*.js等文件4.2 “白屏”深度诊断从网络请求到 DOM 渲染的四层检查白屏不是单一错误而是前端加载链断裂。按顺序排查Network Tab 检查F12 → Network → 刷新页面 → 查看index.html是否 200main.*.js是否 404。若 404说明collectstatic未执行或STATIC_ROOT配置错误Console Tab 检查查看是否有Failed to load resource: the server responded with a status of 404 (Not Found)定位缺失文件路径Elements Tab 检查右键空白处 →Inspect Element看div idroot/div是否存在。若存在但为空说明 React 应用未挂载检查doccano/frontend/src/index.js中ReactDOM.render()调用是否被注释Application Tab 检查Storage → Local Storage查看auth_token是否存在。若不存在说明登录 API 调用失败检查http://localhost:8000/v1/auth/login/是否返回 200 及 token 字段。实操心得我在 macOS 上遇到过 Safari 白屏而 Chrome 正常原因是 Safari 的localStorage限制更严格。解决方案是在doccano/settings.py中添加SESSION_COOKIE_SAMESITE Lax并重启 server。这不是 doccano bug而是浏览器策略演进带来的兼容性问题。4.3 中文支持陷阱字体、编码、输入法三重关卡doccano 默认支持 UTF-8但中文显示仍可能出问题字体缺失Linux 服务器常无中文字体导致标签栏显示方块。解决sudo apt-get install fonts-wqy-zenheiUbuntu或brew install fontconfig brew tap-new homebrew/cask-fonts brew install --cask font-wqy-zenheimacOS文件编码错误上传.txt时若用 GBK 编码保存doccano 会读取为乱码。强制要求所有标注文件用 UTF-8 without BOM 编码VS Code 右下角可切换输入法冲突Windows 上用搜狗输入法打标时快捷键Ctrl1可能被输入法拦截。解决在搜狗设置 → 快捷键 → 关闭所有Ctrl数字组合键。4.4 性能瓶颈预警当标注变慢时先查这三件事SQLite 文件过大单个项目超过 10 万条样本时SQLite 查询延迟显著上升。监控ls -lh db.sqlite3若 200MB考虑迁移到 PostgreSQL浏览器内存泄漏Chrome 标注 2 小时后内存占用超 2GB。缓解每 2 小时刷新页面或改用 Firefox内存管理更优前端未启用 gzipDjango 默认不压缩静态文件。在doccano/settings.py中添加MIDDLEWARE [django.middleware.gzip.GZipMiddleware] GZIP_CONTENT_TYPES [ text/css, text/javascript, application/javascript, application/x-javascript, application/json, ]5. 后续可扩展方向从单机标注到团队协作的平滑演进完成本地安装只是起点。基于 doccano 的实际项目经验我建议按此路径演进第 1 周单机验证用本文流程跑通一个项目导出 100 条标注数据喂给spaCy训练 NER 模型验证标注质量。重点观察标签一致性、边界模糊样本处理、多人标注分歧率。第 2 周团队接入修改doccano/settings.pyALLOW_SIGNUP True开放注册DEFAULT_ROLE annotator新用户默认为标注员EMAIL_BACKEND django.core.mail.backends.console.EmailBackend开发期邮件输出到终端创建reviewer用户组分配审核权限。第 3 周生产加固数据库pip install psycopg2-binary修改DATABASES配置指向 PostgreSQL反向代理用 Nginx 代理http://localhost:8000启用 HTTPS 和 basic auth备份每日crontab执行pg_dump或sqlite3 db.sqlite3 .dump backup.sql。第 4 周智能增强集成transformers模型做预标注在doccano/frontend/src/components/LabelingPage.js中调用自建 API 返回预测结果用户只需修正而非从零标注。实测可提升标注效率 3 倍。最后分享一个小技巧当你需要快速对比两个标注版本时不要手动翻页。在Export页面勾选Include annotation history导出的 JSONL 会包含每次修改的时间戳和操作者用pandas加载后df.groupby([text, label]).size().unstack(fill_value0)即可生成标注一致性矩阵。这比任何第三方工具都直接。我在实际使用中发现最浪费时间的从来不是安装本身而是安装后没人告诉你doccano 的project_id是 UUID不是数字 ID导出的 JSONL 每行必须是独立 JSON 对象不能有逗号分隔label_config的 XML 标签名区分大小写。这些细节往往要等你导出数据喂给模型时报错才暴露。所以本文所有步骤都附带了即时验证点——不是为了让你“装完就走”而是确保你装完就能用用完就有产出。