Registry / data / dvc
library3.67.1pypypi✓ verified 25d ago

DVC (Data Version Control) extends Git to handle large files and machine learning pipelines, providing version control for datasets and models, and enabling reproducible ML workflows. It stores data and model files in a cache outside of Git, supporting various remote storage platforms (S3, Azure, Google Cloud, SSH, etc.). The current version is 3.67.1, with frequent releases.

pip install dvc
INSTALL
IMPORT
SIG · DVC
D
dvc
datapythonv3.67.1
Install
21.8s avg
Import
1274ms
Disk
203MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.67.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 23.1s
py 3.11
✓ —
✓ 23.95s
py 3.12
✓ —
✓ 20.5s
py 3.13
✓ —
✓ 19.6s
py 3.9
1/2 runs
1/2 runs
203MB installed
● package 203MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

dvc.api
import dvc.api
The primary module for programmatic interaction with DVC-tracked data and experiments.

This quickstart first sets up a minimal DVC project using shell commands (simulated via `subprocess`) to initialize DVC within a Git repository and track a `data.csv` file. It then demonstrates how to use the `dvc.api.read()` function in Python to programmatically access the content of the DVC-tracked file.

import os import subprocess import dvc.api # --- CLI Setup (normally run in shell) --- # This part simulates initial DVC project setup if not already done. # In a real scenario, you'd run these in your terminal. def setup_dvc_project(): if not os.path.exists('dvc_quickstart_repo'): os.makedirs('dvc_quickstart_repo') os.chdir('dvc_quickstart_repo') if not os.path.exists('.git'): subprocess.run(['git', 'init', '-b', 'main'], check=True) # Ensure dvc is initialized if not os.path.exists('.dvc'): subprocess.run(['dvc', 'init'], check=True) subprocess.run(['git', 'add', '.dvcignore', '.dvc/config', '.dvc/.gitignore'], check=True) subprocess.run(['git', 'commit', '-m', 'Initialize DVC'], check=True) # Create a dummy data file with open('data.csv', 'w') as f: f.write('col1,col2\n1,A\n2,B\n3,C\n') # Add data to DVC and commit the .dvc file to Git subprocess.run(['dvc', 'add', 'data.csv'], check=True) subprocess.run(['git', 'add', 'data.csv.dvc'], check=True) subprocess.run(['git', 'commit', '-m', 'Add data.csv'], check=True) print("DVC project setup complete in 'dvc_quickstart_repo'") os.chdir('..') # Go back to original directory # Run the setup setup_dvc_project() # --- Python API Usage --- # Now, demonstrate reading the DVC-tracked file programmatically repo_path = 'dvc_quickstart_repo' file_path = 'data.csv' try: # Read the content of the DVC-tracked file # dvc.api will automatically handle fetching from cache or remote if needed content = dvc.api.read( path=file_path, repo=repo_path, rev='HEAD' # Or a specific Git commit/tag/branch ) print(f"\nContent of {file_path} from DVC repo '{repo_path}':\n{content}") # Example: Reading a specific parameter from params.yaml if it existed # (This example assumes no params.yaml is set up in the quickstart for simplicity) # params_content = dvc.api.read(path='params.yaml', repo=repo_path, rev='HEAD') # import yaml # params = yaml.safe_load(params_content) # print(f"Parameters: {params}") except Exception as e: print(f"An error occurred while reading DVC-tracked file: {e}")
dvc --version
Debug
Known issues
breakingIn DVC 3.63.0, the `dvc status --cloud` command changed its behavior for directory targets. It now treats the path as a specific dataset, rather than recursively searching for `.dvc` and `dvc.yaml` files within it.
fix
To restore the previous recursive behavior when checking a directory with `dvc status --cloud`, add the `--recursive` option.
affects: >=3.63.0
breakingUpgrading from DVC 2.x to 3.x involves a change in how file hashes are calculated. This means that a minor change to a file within a DVC-tracked directory can trigger a full migration of the entire directory to the 3.x hashing scheme.
fix
After migrating your local repository to 3.x (e.g., using `dvc cache migrate --dvc-files`), you may need to re-upload all 3.x data to your remote storage for consistency. Consider the impact on remote storage and network usage.
affects: 3.x (from 2.x)
gotchaIt is a common beginner mistake to use `dvc add` too broadly or to run `dvc commit` too frequently alongside every `git commit`. This can lead to tracked pipeline outputs being re-added as data, or excessive cache usage for minor changes.
fix
Use `dvc add` for initial data versioning and `dvc commit` only when data or pipelines are in a stable, significant state. For intermediate or pipeline-generated outputs, rely on DVC's pipeline system (`dvc.yaml`) which handles caching automatically. Use the `--no-commit` option with `dvc add` or `dvc run` if you want to track data without immediately caching it.
affects: All
gotchaDVC 3.66.0 introduced a restriction on the `pathspec` dependency to `<1`. This could cause conflicts if other tools in your environment (e.g., `black` formatter) required `pathspec>=1`. DVC 3.67.0 subsequently added support for `pathspec v1`.
fix
If encountering `pathspec` dependency conflicts around DVC 3.66.0, upgrade to DVC 3.67.0 or later, which includes `pathspec v1` support, or adjust your environment to ensure compatible `pathspec` versions for all tools.
affects: 3.66.0
Errors
Common errors & fixes
Command 'dvc' not found
DVC is not installed or its executable path is not included in the system's PATH environment variable, making the command inaccessible from the terminal.
fix
Install DVC using `pip install dvc` (or `conda install -c conda-forge dvc`) and then restart your terminal or re-source your shell configuration file (e.g., `.bashrc`, `.zshrc`) to update the PATH.
ERROR: failed to pull data from the cloud - Checkout failed for following targets: ... WARNING: Cache 'xxxx' not found.
DVC is unable to find the required data files in the configured remote storage or in the local cache, often because the corresponding data was not `dvc push`ed from the original project or the cache is corrupted/out of sync.
fix
Ensure the data was `dvc push`ed from the source repository. If the data exists in the remote, try `dvc pull` again. If the local cache is suspected to be corrupted, use `dvc cache dir --local` to locate the cache and manually clean problematic entries if necessary, or consider `dvc destroy -f` if you are confident in remote data integrity and need to reset the cache.
ERROR: not a dvc repository (checked up to mount point '/...')
This command was executed outside of an initialized DVC repository, meaning DVC cannot find the `.dvc` directory that marks the project root.
fix
Navigate to the root directory of your DVC project (where the `.dvc` folder is located) or initialize a DVC repository using `dvc init` if you intend to start a new DVC project in the current directory.
ERROR: failed to push data to the cloud - X files failed to upload.
DVC encountered issues transferring data to the remote storage, commonly due to network problems, incorrect remote configuration (e.g., wrong URL, insufficient credentials), or permission issues on the remote.
fix
Verify your remote configuration (`dvc remote list -v`, `dvc remote modify`) and ensure correct authentication credentials. Check network connectivity to the remote and try running `dvc push -v` for more verbose output to pinpoint the exact failure reason. For S3 remotes, consider installing `dvc-s3` for automatic retries.
ERROR: unexpected error - [Errno 2] No such file or directory:
This generic error often indicates that DVC cannot find a specified file or directory, which can occur during `dvc run` if an input/output path is incorrect, during `dvc pull` if data is missing from the cache or remote, or when dealing with misconfigured cache types (e.g., `symlink` on incompatible filesystems).
fix
Double-check that all file paths referenced in your `dvc.yaml` stages or DVC commands exist and are accessible. If pulling data, ensure the remote contains the expected files. If `cache.type` is set to `symlink`, try switching to `copy` or `hardlink` if the cache directory is on a different drive than the workspace, or if the filesystem doesn't fully support symlinks.
Upgrade
Version history
3.67.1latest on PyPI · released Mar 31, 2026
Audit
Dependencies
pythonrequiredRequires Python >=3.9
dvc-datarequiredCore DVC component for data handling
pathspecrequiredRequired for `.dvcignore` and file pattern matching.
psutiloptionalNeeded for `dvc version` to report file system information accurately.
Agent activity
27 hits · last 30 days
node
24
OpenAI (training)
1
Resources
dvc — pip install dvc · libregistry