# @deepnote/convert 中文文档

规范地址：https://npmcn.com/package/%40deepnote/convert/

版本：5\.0\.0
npm 元数据更新时间：2026-11-05T11:42:22.781Z
中文译文更新时间：2026-11-11T20:29:43.161Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deepnote/convert
原文对照：https://npmcn.com/package/%40deepnote/convert/?lang=original
项目主页：https://github.com/deepnote/deepnote#readme
源码仓库：https://github.com/deepnote/deepnote

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：383 kB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.14\.0
- 运行依赖：5 个
- 首次发布：2025-10-31T16:07:42.282Z
- 最新版本发布：2026-11-05T11:42:22.590Z
- 近 30 天下载量：8181（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 21 个）

## 中文简介

Deepnote 项目文件之间的双向转换器( E)`.deepnote`)和多种笔记本格式: Jupyter(`.ipynb`),克特尔多(`.qmd`(百分比) (百分比)`.py`马里莫和马里莫`.py`) (中文(简体) ).

## 安装

```sh
npm install @deepnote/convert
```

也可以使用：`pnpm add @deepnote/convert`、`yarn add @deepnote/convert`、`bun add @deepnote/convert`

## README

# @deepnote/转换

Deepnote 项目文件之间的双向转换器( E)`.deepnote`)和多种笔记本格式: Jupyter(`.ipynb`),克特尔多(`.qmd`(百分比) (百分比)`.py`马里莫和马里莫`.py`) (中文(简体) ).

```bash
# Convert any supported format to Deepnote
npx @deepnote/convert notebook.ipynb
npx @deepnote/convert document.qmd
npx @deepnote/convert notebook.py  # percent or marimo format

# Convert Deepnote to any supported format
npx @deepnote/convert project.deepnote                      # defaults to Jupyter
npx @deepnote/convert project.deepnote --outputFormat quarto
npx @deepnote/convert project.deepnote --outputFormat percent
npx @deepnote/convert project.deepnote --outputFormat marimo
```

## 安装

```bash
npm install -g @deepnote/convert
```

## 支持的格式

| 格式 | 延长 | 说明 |
| --- | --- | --- |
| **朱比特语Name** | `.ipynb` | 标准Jupyter Notebook JSON格式 |
| **夸多语Name** | `.qmd` | 带有代码块的 Quarto 标记下文档 |
| **百分比** | `.py` | Python 文件为 `# %%` 单元格标记( VS 代码, Spyder) |
| **马里莫** | `.py` | 马里莫反应笔记本 `@app.cell` 装饰器 |

## CLI 使用量

软件包提供了 `deepnote-convert` 用于双向转换的命令行工具.

### 转换为深注

任何支持的格式转换为 `.deepnote` 自动 :

```bash
# Single file
deepnote-convert notebook.ipynb
deepnote-convert document.qmd
deepnote-convert notebook.py  # auto-detects percent vs marimo

# Directory of files — one single-notebook .deepnote per notebook (into the dir, or use -o <dir>)
deepnote-convert path/to/notebooks/
```

### 从深音转换

使用 `--outputFormat` 选择目标格式(默认为 `jupyter`:

```bash
deepnote-convert project.deepnote                        # → Jupyter notebooks
deepnote-convert project.deepnote --outputFormat jupyter # → Jupyter notebooks
deepnote-convert project.deepnote --outputFormat quarto  # → Quarto documents
deepnote-convert project.deepnote --outputFormat percent # → Percent format files
deepnote-convert project.deepnote --outputFormat marimo  # → Marimo notebooks
```

### 选项

#### `--projectName <name>`

设置 Deepnote 项目的自定义名称( 当转换为 `.deepnote`:

```bash
deepnote-convert notebook.ipynb --projectName "My Analysis"
```

#### `-o, --outputPath <path>`

指定保存输出的地点 :

```bash
# To Deepnote: Save to a specific file or directory
deepnote-convert notebook.ipynb -o output/project.deepnote
deepnote-convert notebook.ipynb -o output/

# From Deepnote: Specify output directory
deepnote-convert project.deepnote -o output/notebooks/
```

#### `--outputFormat <format>`

转换时选择输出格式 `.deepnote`数字 :

```bash
deepnote-convert project.deepnote --outputFormat quarto
```

选项 : `jupyter` (违约), `quarto`, (中文(简体) ), `percent`, (中文(简体) ), `marimo`

#### `--singleFile`

默认转换时 **改为** 深注,单元格输出在 a 下拆分为单独的快照文件 `snapshots/` 目录 `.deepnote`,将主文件输出为无。 过 `--singleFile` 将产出插入单项 `.deepnote` 并跳过快照:

```bash
deepnote-convert notebook.ipynb --singleFile
```

### 实例

```bash
# Jupyter → Deepnote
deepnote-convert titanic.ipynb --projectName "Titanic Analysis"
deepnote-convert ./notebooks -o ./output

# Quarto → Deepnote
deepnote-convert analysis.qmd --projectName "Data Report"

# Percent → Deepnote (auto-detected from # %% markers)
deepnote-convert script.py

# Marimo → Deepnote (auto-detected from @app.cell decorators)
deepnote-convert reactive.py

# Deepnote → various formats
deepnote-convert project.deepnote                        # Jupyter (default)
deepnote-convert project.deepnote --outputFormat quarto  # Quarto
deepnote-convert project.deepnote --outputFormat percent # Percent
deepnote-convert project.deepnote --outputFormat marimo  # Marimo
```

### Python 文件检测

转换时 `.py` 文件,转换器自动检测格式 :

-   **马里莫**: 包含 `import marimo` 财务报告和审定财务报表 `@app.cell` 装饰器
-   **百分比**: 包含 `# %%` 单元格标记

在目录扫描时, 使用明确的命名 :

-   `*.marimo.py` 用于 Marimo 文件
-   `*.percent.py` % 格式文件

### 无损失回转转换

转换器支持 Jupyter 的无损失回转转换 :

-   **深注 · Jupyter · 深注**: 在 Jupyter 单元格元数据中保存所有深注专用元数据
-   **Jupyter – 深注 – Jupyter →**: 在添加 Deepnote 元数据的同时保留原Jupyter 内容

其他格式(Quarto,Percent,Marimo)保留了内容和结构,但可能不会保留所有Deepnote特定元数据.

### 平台兼容性

自朱皮特以来`.ipynb`)是标准格式,来自使用Jupyter的云平台的笔记本被完全支持元数据保存:

| 平台 | 状态 | 页:1 |
| --- | --- | --- |
| **谷歌科拉布语Name** | 完全兼容 | 保存 Colab 单元格标识、 窗体单元格、 GPU 设置 |
| **亚马逊SageMaker** | 完全兼容 | 保护标记、培训/参考标记 |
| **卡格尔** | 完全兼容 | 保存 UUID, 单元格 GUID, 隐藏输入/输出 |
| **Azure ML 笔记本** | 完全兼容 | 有 Azure 元数据的标准 Jupyter |
| **黄道/湿道** | 完全兼容 | 标准 Jupyter 格式 |

平台专用的单元格元数据在圆通转换过程中被保存,允许笔记本在Deepnote中被编辑并导出回原平台而不会丢失设置.

## 程序用途

### 转换为深注

```typescript
import {
  convertIpynbFileToDeepnoteFile,
  convertQuartoFileToDeepnoteFile,
  convertPercentFileToDeepnoteFile,
  convertMarimoFileToDeepnoteFile,
} from "@deepnote/convert";

// Each call converts ONE source notebook into ONE single-notebook .deepnote file.

// From Jupyter
await convertIpynbFileToDeepnoteFile("notebook.ipynb", {
  outputPath: "output.deepnote",
  projectName: "My Project",
});

// From Quarto
await convertQuartoFileToDeepnoteFile("document.qmd", {
  outputPath: "output.deepnote",
  projectName: "My Project",
});

// From Percent
await convertPercentFileToDeepnoteFile("script.py", {
  outputPath: "output.deepnote",
  projectName: "My Project",
});

// From Marimo
await convertMarimoFileToDeepnoteFile("notebook.py", {
  outputPath: "output.deepnote",
  projectName: "My Project",
});
```

### 从深音转换

```typescript
import {
  convertDeepnoteFileToJupyterFiles,
  convertDeepnoteFileToQuartoFiles,
  convertDeepnoteFileToPercentFiles,
  convertDeepnoteFileToMarimoFiles,
} from "@deepnote/convert";

// To Jupyter
await convertDeepnoteFileToJupyterFiles("project.deepnote", {
  outputDir: "./jupyter-notebooks",
});

// To Quarto
await convertDeepnoteFileToQuartoFiles("project.deepnote", {
  outputDir: "./quarto-docs",
});

// To Percent
await convertDeepnoteFileToPercentFiles("project.deepnote", {
  outputDir: "./percent-scripts",
});

// To Marimo
await convertDeepnoteFileToMarimoFiles("project.deepnote", {
  outputDir: "./marimo-notebooks",
});
```

### 纯转换( 无文件 I/ O)

供方案使用内存数据:

```typescript
import fs from "node:fs/promises";
import { deserializeDeepnoteFile } from "@deepnote/blocks";
import {
  convertDeepnoteToJupyterNotebooks,
  convertDeepnoteToQuartoDocuments,
  convertDeepnoteToPercentNotebooks,
  convertDeepnoteToMarimoApps,
} from "@deepnote/convert";

// Read and deserialize the Deepnote file
const yamlContent = await fs.readFile("project.deepnote", "utf-8");
const deepnoteFile = deserializeDeepnoteFile(yamlContent);

// Convert to any format (pure functions, no I/O)
const jupyterNotebooks = convertDeepnoteToJupyterNotebooks(deepnoteFile);
const quartoDocuments = convertDeepnoteToQuartoDocuments(deepnoteFile);
const percentNotebooks = convertDeepnoteToPercentNotebooks(deepnoteFile);
const marimoApps = convertDeepnoteToMarimoApps(deepnoteFile);

// Work with the results in memory
for (const { filename, notebook } of jupyterNotebooks) {
  console.log(`${filename}: ${notebook.cells.length} cells`);
}
```

## 许可证

阿帕奇 - 2.0

## 常见问题

### @deepnote/convert 是什么？

Deepnote 项目文件之间的双向转换器\( E\)\.deepnote\)和多种笔记本格式: Jupyter\(\.ipynb\),克特尔多\(\.qmd\(百分比\) \(百分比\)\.py马里莫和马里莫\.py\) \(中文\(简体\) \)\.

### 如何安装 @deepnote/convert？

在项目目录运行 npm install @deepnote/convert，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 deepnote-convert，可以用 npx deepnote-convert 直接运行。

### @deepnote/convert 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @deepnote/convert 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @deepnote/convert 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.14\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @deepnote/convert 可以商用吗？

@deepnote/convert 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @deepnote/convert 的下载量有多少？

根据 npm 官方下载统计，@deepnote/convert 在 2026/10/12 – 2026/11/10 这 30 天内被下载 8,181 次，日均约 273 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deepnote/convert 还在维护吗？

最新版本 5\.0\.0 发布于 2026/11/05（6 天前）；至今共发布 24 个版本，其中过去 12 个月发布了 21 个；首次发布于 2025/11/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。