开始使用
开始使用
首页安装快速开始使用案例用户指南命令参考
addartifactscachecheck-ignorecheckoutcommitconfigdagdata statusdestroydiffdoctorexpfetchfreezegcget-urlgetimport-dbimport-urlimportinitinstalllist-urllistmetricsmoveparamsplotspullpushqueueremoteremove复现根目录暂存状态工作室解冻取消保护更新版本
Python API 参考贡献更新日志 VS Code 扩展 DVCLive
在 GitHub 上编辑

import

从另一个 DVC 或 Git 仓库中下载被追踪的文件或目录到 工作区，并对其进行追踪（会创建一个导入用的 .dvc 文件）。

另请参阅我们的 dvc.api.open() Python API 函数。

概要 

usage: dvc import [-h] [-q | -v]
                  [-o <path>] [-f] [--rev <commit>]
                  [--no-exec | --no-download]
                  [-j <number>]
                  [--config <path>] [--remote <name>]
                  [--remote-config [<name>=<value> ...]]
                  url path

positional arguments:
  url              Location of DVC or Git repository to download from
  path             Path to a file or directory within the repository

描述

提供了一种简便方式，用于复用任何 DVC 仓库（例如数据集、中间结果、机器学习模型）或 Git 仓库（例如代码、小型图像/其他文件）中被追踪的文件或目录。dvc import 会下载位于 url 中 path 处的目标文件或目录，并在本地项目中对其进行追踪。这样可以在数据源发生变化时更新导入内容（参见 dvc update）。

可使用 dvc list 浏览仓库内容，以查找可导入的文件或目录。

注意：dvc get 相当于此命令执行的第一步（仅下载数据）。

导入的数据会被 缓存，并通过硬链接（或复制）方式链接到当前工作目录，并保留原始文件名（例如 data.txt），或通过 --out 指定位置存放。同时会在同一位置创建一个导入 .dvc 文件（例如 data.txt.dvc），类似于下载数据后使用 dvc add 的效果。

DVC 不会将从其他 DVC 仓库导入的数据推送到远程存储。dvc pull 将始终从原始数据源下载。

url 参数指定包含数据源的 DVC 或 Git 仓库地址，支持 HTTP 和 SSH 协议（例如 [user@]server:project.git）。url 也可以是本地文件系统路径（包括当前项目，例如 .）。

path 参数指定要下载的文件或目录（支持被追踪目录内的路径）。该路径应相对于仓库根目录（当 url 为本地路径时支持绝对路径）。请注意，被 DVC 追踪的目标必须存在于仓库的 dvc.yaml 或 .dvc 文件中。

如需从 S3、SSH、HTTP 等其他受支持的位置下载并追踪数据，请参见 dvc import-url。

.dvc 文件支持引用托管在 Git 服务器上的外部 DVC 仓库中的数据。在这种 .dvc 文件中，deps 字段指定 url 和数据 path，而 outs 字段包含工作区中的对应本地路径。它记录了足够的元数据，使 DVC 能高效判断本地副本是否已过期。

要真正实现数据的版本管理，请使用 git add（以及 git commit）提交导入生成的 .dvc 文件。

⚠️ 注意事项和限制：

  • 源 DVC 仓库应配置有包含目标数据的dvc remote default，此命令才能正常运行。
  • 上述要求的唯一例外是本地仓库，此时 DVC 会优先尝试从其缓存中复制数据。
  • 对链式导入（即导入的数据本身是从另一个仓库导入至源仓库的）的支持有限。
  • 请注意，dvc repro 不会检查或更新导入的 .dvc 文件（参见 dvc freeze），请使用 dvc update 将导入内容从数据源更新至最新。

选项

  • -o <路径>，--out <路径> - 指定工作区中用于放置下载文件或目录的目标路径（而不是使用当前工作目录）。

  • -f, --force - 当使用 --out 指定本地目标文件或目录时，如果这些路径已存在，操作将失败。使用此标志会强制执行操作，导致命令覆盖现有的本地文件/目录。

  • --rev <提交版本> - 仓库的提交哈希、分支或标签名称等（任何Git 版本），用于指定从中下载文件或目录的版本。若未指定此选项，默认使用默认分支中的最新提交。

    请注意，这会在导入的 .dvc 文件中添加一个 rev 字段，将其固定到特定版本。这可能会影响 dvc update 的行为（参见下方的导入并更新固定版本示例）。

  • --no-exec - 创建导入 .dvc 文件但不访问 url（假定数据源有效）。当你需要快速定义项目导入并在稍后导入数据时，此选项非常有用（可使用 dvc update 完成操作）。

  • --no-download - 创建包含源数据信息（仓库 URL 和版本）的导入 .dvc 文件，但不下载关联的数据。当你需要跟踪远程数据的变化但暂时不想占用本地存储空间时，此选项非常有用。数据可在之后通过 dvc pull 下载。文件版本可通过 dvc update --no-download 更新。

  • -j <数字>，--jobs <数字> - DVC 从远程下载数据时使用的并行任务数量。默认值为 4 * cpu_count()。使用更多任务可能会加快操作速度。注意：可通过 dvc remote modify 的 jobs 配置选项在源仓库中设置默认值。

  • --config <path> - 指向 配置文件 的路径，该文件将与目标仓库中的配置合并。

  • --remote <name> - 在目标仓库中设置为默认的 dvc remote 名称。

  • --remote-config [<name>=<value> ...] - 要与远程存储配置（默认或通过 --remote 指定的远程）合并的 dvc remote 配置选项。

  • -h, --help - 打印使用说明/帮助信息，然后退出。

  • -q, --quiet - 不向标准输出写入任何内容。如果没有问题则以 0 退出，否则以 1 退出。

  • -v, --verbose - 显示详细的跟踪信息。

示例

该命令的一个简单用例是从外部DVC 仓库导入数据集，例如我们的入门示例仓库。

$ dvc import git@github.com:iterative/example-get-started \
             data/data.xml
Importing 'data/data.xml (git@github.com:iterative/example-get-started)'
-> 'data.xml'

与 dvc get 不同，此命令不仅下载数据文件，还会创建一个带有指向数据源链接的导入 .dvc 文件（如上文描述所述）。（此 .dvc 文件之后可用于更新导入。）查看 data.xml.dvc：

md5: 7de90e7de7b432ad972095bc1f2ec0f8
frozen: true
wdir: .
deps:
  - path: data/data.xml
    repo:
      url: git@github.com:iterative/example-get-started
      rev_lock: 6c73875a5f5b522f90b5afa9ab12585f64327ca7
outs:
  - md5: a304afb96060aad90176268345e10355
    path: data.xml
    cache: true

上述多个值来自原始的 .dvc 文件，即外部 DVC 仓库中的文件。repo 下的 url 和 rev_lock 子字段分别用于保存依赖项的来源和版本。

示例：导入并更新固定版本

要导入文件/目录的特定版本，可以使用 --rev 选项：

$ dvc import --rev cats-dogs-v1 \
             git@github.com:iterative/dataset-registry.git \
             use-cases/cats-dogs
Importing
'use-cases/cats-dogs (git@github.com:iterative/dataset-registry.git)'
-> 'cats-dogs'

使用此选项时，导入的 .dvc 文件在 repo 下也会包含一个 rev 子字段：

deps:
  - path: use-cases/cats-dogs
    repo:
      url: git@github.com:iterative/dataset-registry.git
      rev: cats-dogs-v1
      rev_lock: 0547f5883fb18e523e35578e2f0d19648c8f2d5c

如果 rev 是一个 Git 分支或标签（其底层提交可能会变化），那么该数据源可能在稍后时间有更新。若要将其更新至最新状态（并更新 .dvc 文件中的 rev_lock），只需使用 dvc update <stage>.dvc。如果 rev 是一个特定的提交哈希（不会改变），则不带选项的 dvc update 不会对导入的 .dvc 文件产生影响。你可以通过 dvc update --rev 强制将其更新到另一个提交：

$ dvc update --rev cats-dogs-v2 cats-dogs.dvc

在上面的例子中，新的 .dvc 文件中 rev 的值将是 master（一个分支），因此后续可以正常进行更新。

示例：数据注册表

如果你查看我们的 数据集注册表 项目，会发现它被组织成不同的目录，例如 tutorials/versioning 和 use-cases/，这些目录中包含跟踪不同数据集的 .dvc 文件。由于这种简单的结构，其数据文件可以通过 dvc get 和 dvc import 轻松地在多个其他项目之间共享。例如：

$ dvc get https://github.com/iterative/dataset-registry \
          tutorials/versioning/data.zip

用于我们的 版本控制教程

或者

$ dvc import git@github.com:iterative/dataset-registry.git \
             use-cases/cats-dogs

dvc import 提供了一种更好的方式来引入外部 DVC 仓库 中跟踪的数据文件，因为它保存了当前项目与源仓库之间的连接。这意味着足够的信息会被记录在一个导入的 .dvc 文件中，以便在未来需要时能够 重现 下载相同版本的数据。这是通过 repo 字段实现的，例如（与上述导入命令对应）：

frozen: true
deps:
  - path: use-cases/cats-dogs
    repo:
      url: git@github.com:iterative/dataset-registry.git
      rev_lock: 0547f5883fb18e523e35578e2f0d19648c8f2d5c
outs:
  - md5: b6923e1e4ad16ea1a7e2b328842d56a2.dir
    path: cats-dogs
    cache: true

详见我们 数据注册表 使用场景的完整说明。

示例：从任意 Git 仓库导入

你甚至可以从普通的 Git 仓库（非 DVC 仓库）中导入文件。例如，让我们从 GSA 的数据仓库 导入一个数据集：

$ dvc import git@github.com:GSA/data \
           enterprise-architecture/it-standards.csv
Importing ...

请注意，Git 跟踪的文件也可以从 DVC 仓库中导入。

文件已被导入，同时生成了一个导入用的 .dvc 文件。查看 it-standards.csv.dvc：

deps:
  - path: enterprise-architecture/it-standards.csv
    repo:
      url: git@github.com:GSA/data
      rev_lock: af6a1feb542dc05b4d3e9c80deb50e6596876e5f
outs:
  - md5: 7e6de779a1ab286745c808f291d2d671
    path: it-standards.csv

repo 下的 url 和 rev_lock 子字段分别用于保存依赖项的来源和版本。

示例：链式导入

DVC 支持导入那些本身是从其他仓库导入到源仓库的数据，只要导入链中的所有仓库（及其 dvc remote default）都能从最终目标仓库访问即可。

考虑一个包含三个 DVC 仓库（A、B 和 C）的例子。DVC 仓库 /repo/a 包含一个通过 dvc add 跟踪的 data.csv 文件：

/repo/a
├── data.csv
└── data.csv.dvc

在仓库 B 中，我们从 A 导入 data.csv 到一个子目录中：

$ dvc import /repo/a data.csv --out training/data.csv

项目 B 当然也可能包含自身独有的其他文件，例如：

/repo/b
└── training
    ├── data.csv
    ├── data.csv.dvc
    ├── labels
    │   ├── test.txt
    │   └── truth.txt
    └── labels.dvc

注意，training/labels 目录（不是导入的）也在 B 中单独进行了跟踪。

如果我们检查 training/data.csv.dvc，可以看到导入源是仓库 A（/repo/a）：

deps:
  - path: data.csv
    repo:
      url: /repo/a
      rev_lock: 32ab3ddc8a0b5cbf7ed8cb252f93915a34b130eb
outs:
  - md5: acbd18db4cc2f85cedef654fccc4a4d8
    size: 3234523
    path: data.csv

现在假设我们在第三个仓库 C 中运行以下命令：

$ dvc import /repo/b training

这将生成如下目录结构，其中包含一个链式导入和一个普通导入：

/repo/c
├── training
│   ├── data.csv
│   └── labels
│       ├── test.txt
│       └── truth.txt
└── training.dvc
  • training/data.csv 从 A 导入到 B，再从 B 导入到 C
  • training/labels/ 直接从 B 导入到 C

然而，training.dvc 仅引用了仓库 B（/repo/b）：

deps:
  - path: training
    repo:
      url: /repo/b
      rev_lock: 15136ed84b59468b68fd66b8141b41c5be682ced
outs:
  - md5: e784c380dd9aa9cb13fbe22e62d7b2de.dir
    size: 27
    nfiles: 3
    path: training

每次我们在 C 中执行 dvc import 或 dvc update* 将 training/ 导入（或甚至 dvc pull 它）时，DVC 都会先查找 B 中 training 的内容，并发现 training/data.csv 本身也是一个导入项。然后 DVC 会按需解析该链（在 A 中找到 data.csv）。

*注意：当在仓库 C 中运行 dvc update training 时，DVC 只会检查 training/ 在仓库 B 中是否发生了变化。因此，如果 data.csv 仅在 A 中发生了更改，则在 B 中运行 dvc update training/data.csv 之前，training/data.csv 不会在 C 中更新。

这意味着当在仓库 C 中运行 dvc import 时，必须能够访问 A 和 B 两个仓库，否则导入链的解析将失败。

在整个导入链中的所有仓库都必须能访问其 dvc remote default（仓库 C 必须拥有所有适当的凭据）。

示例：设置默认远程 

$ dvc import https://github.com/iterative/example-get-started-s3 data/prepared --remote myremote
...
$ cat prepared.dvc
deps:
  - path: data/prepared
    repo:
      url: https://github.com/iterative/example-get-started-s3
      rev_lock: 8141b41c5be682ced15136ed84b59468b68fd66b
      remote: myremote
outs:
  - md5: e784c380dd9aa9cb13fbe22e62d7b2de.dir
    size: 27
    nfiles: 3
    path: prepared

示例：为默认远程设置 AWS 配置文件 

$ dvc import https://github.com/iterative/example-get-started-s3 data/prepared --remote-config profile=myprofile
...
$ cat prepared.dvc
deps:
  - path: data/prepared
    repo:
      url: https://github.com/iterative/example-get-started-s3
      rev_lock: 8141b41c5be682ced15136ed84b59468b68fd66b
      remote:
        profile: myprofile
outs:
  - md5: e784c380dd9aa9cb13fbe22e62d7b2de.dir
    size: 27
    nfiles: 3
    path: prepared

示例：创建新的 AWS S3 远程存储并设为默认值

如果同名远程已存在，则其配置将与 --remote-config 提供的选项合并。

$ dvc import https://github.com/iterative/example-get-started-s3 data/prepared \
    --remote myremote \
    --remote-config url=s3://mybucket/mypath profile=myprofile
...
$ cat prepared.dvc
deps:
  - path: data/prepared
    repo:
      url: https://github.com/iterative/example-get-started-s3
      rev_lock: 8141b41c5be682ced15136ed84b59468b68fd66b
      config:
        core:
          remote: myremote
        remote:
          myremote:
            url: s3://mybucket/mypath
            profile: myprofile
outs:
  - md5: e784c380dd9aa9cb13fbe22e62d7b2de.dir
    size: 27
    nfiles: 3
    path: prepared

示例：为特定远程设置 AWS 密钥

在此示例中，你可以使用 --config 指向一个被 git 忽略的配置文件，而不是在 dvcfile 中使用 --remote myremote 和 --remote-config 暴露你的密钥信息。--config 所用配置文件的格式与 dvc config 生成的格式相同。

$ cat myconfig
[core]
  remote = myremote

[remote "myremote"]
  access_key_id = myaccesskeyid
  secret_access_key = mysecretaccesskey
$ cat .gitignore # make sure you are not commiting this file to git
...
/myconfig
...
$ dvc import https://github.com/iterative/example-get-started-s3 data/prepared --config myconfig
...
$ cat prepared.dvc
deps:
  - path: data/prepared
    repo:
      url: https://github.com/iterative/example-get-started-s3
      rev_lock: 8141b41c5be682ced15136ed84b59468b68fd66b
      config: myconfig
outs:
  - md5: e784c380dd9aa9cb13fbe22e62d7b2de.dir
    size: 27
    nfiles: 3
    path: prepared
上一页下一页
内容

🐛 发现问题？告诉我们！或者修复它：

在 GitHub 上编辑

❓ 有疑问？加入我们的聊天，我们会为您提供帮助：

Discord 聊天