# How to migrate from Pipenv to uv


Pipenv combines [pip](https://pydevtools.com/handbook/reference/pip.md) and [virtualenv](https://pydevtools.com/handbook/reference/virtualenv.md) into a single tool. [uv](https://pydevtools.com/handbook/reference/uv.md) covers the same ground and adds Python version management, a standards-compliant [pyproject.toml](https://pydevtools.com/handbook/reference/pyproject.toml.md)-based workflow, and significantly faster dependency resolution.

Migrating replaces the [Pipfile](https://pydevtools.com/handbook/reference/pipfile.md) and `Pipfile.lock` with `pyproject.toml` and `uv.lock`, and swaps `pipenv` commands for their `uv` equivalents.

## Automated migration

The [migrate-to-uv](https://osprey-oss.github.io/migrate-to-uv/) tool automates the conversion.

### 1. Run the migration tool

```console
$ uvx migrate-to-uv
```

The tool reads your `Pipfile` and:
- Creates a `pyproject.toml` with `[project]` metadata and `[dependency-groups]`
- Translates `[packages]` to `dependencies` and `[dev-packages]` to the `dev` dependency group
- Generates a `uv.lock` file from the resolved dependencies in `Pipfile.lock`
- Removes `Pipfile` and `Pipfile.lock`

### 2. Verify the result

```console
$ uv sync
$ uv run pytest
```

## Manual migration

If the automated tool doesn't cover your setup, map `Pipfile` sections to `pyproject.toml` by hand.

A typical `Pipfile`:

```toml {filename="Pipfile"}
[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]
requests = ">=2.28"
click = ">=8.0"

[dev-packages]
pytest = ">=7.0"
ruff = "*"

[requires]
python_version = "3.11"
```

Becomes:

```toml {filename="pyproject.toml"}
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.28",
    "click>=8.0",
]

[dependency-groups]
dev = [
    "pytest>=7.0",
    "ruff",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```

Key translations:

| Pipfile | pyproject.toml |
|---|---|
| `[packages]` | `[project] dependencies` |
| `[dev-packages]` | `[dependency-groups] dev` |
| `[requires] python_version` | `[project] requires-python` |
| `[source]` (non-default index) | `[[tool.uv.index]]` |
| `"*"` (any version) | omit the version constraint |

After creating `pyproject.toml`, generate the lockfile:

```console
$ uv lock
$ uv sync
```

Then delete `Pipfile` and `Pipfile.lock`.

## Command equivalents

| Pipenv | uv |
|---|---|
| `pipenv install` | `uv sync` |
| `pipenv install requests` | `uv add requests` |
| `pipenv install --dev pytest` | `uv add --dev pytest` |
| `pipenv uninstall requests` | `uv remove requests` |
| `pipenv run python script.py` | `uv run python script.py` |
| `pipenv run pytest` | `uv run pytest` |
| `pipenv shell` | `source .venv/bin/activate` |
| `pipenv lock` | `uv lock` |
| `pipenv sync` | `uv sync` |
| `pipenv update` | `uv lock --upgrade` |
| `pipenv update requests` | `uv lock --upgrade-package requests` |
| `pipenv graph` | `uv tree` |

> [!TIP]
> `pipenv shell` spawns a subshell. uv keeps the [virtual environment](https://pydevtools.com/handbook/explanation/what-is-a-virtual-environment.md) in `.venv` at the project root. Activate it with `source .venv/bin/activate` (macOS/Linux) or `.venv\Scripts\activate` (Windows), or prefix commands with `uv run` instead of activating.

## Learn More

- [uv: A Complete Guide](https://pydevtools.com/handbook/explanation/uv-complete-guide.md) covers what uv does, how fast it is, the core workflows, and recent releases.
- [uv reference](https://pydevtools.com/handbook/reference/uv.md)
- [migrate-to-uv documentation](https://osprey-oss.github.io/migrate-to-uv/)
- [uv project documentation](https://docs.astral.sh/uv/concepts/projects/)
- [What is a lockfile?](https://pydevtools.com/handbook/explanation/what-is-a-lock-file.md)
- [How to migrate from requirements.txt to pyproject.toml with uv](https://pydevtools.com/handbook/how-to/migrate-requirements.txt.md)
- [How to migrate from Poetry to uv](https://pydevtools.com/handbook/how-to/how-to-migrate-from-poetry-to-uv.md)