0
# Pipenv
1

2
Python Development Workflow for Humans. Pipenv is a Python virtualenv management tool that combines pip and virtualenv functionality into a single tool, automatically creating and managing virtual environments for projects while using Pipfile and Pipfile.lock for dependency management instead of requirements.txt files.
3

4
## Package Information
5

6
- **Package Name**: pipenv
7
- **Language**: Python
8
- **Installation**: `pip install pipenv`
9
- **Requirements**: Python 3.9+
10

11
## Core Imports
12

13
```python
14
import pipenv
15
from pipenv.project import Project
16
from pipenv.environment import Environment
17
```
18

19
CLI usage (most common):
20
```bash
21
pipenv install  # Install packages
22
pipenv shell    # Activate shell
23
pipenv run      # Run commands
24
```
25

26
## Basic Usage
27

28
```python
29
# Programmatic usage - Project management
30
from pipenv.project import Project
31

32
# Create project instance
33
project = Project()
34

35
# Access project information
36
print(f"Project: {project.name}")
37
print(f"Python: {project.environment.python}")
38
print(f"Packages: {list(project.packages.keys())}")
39

40
# Add packages programmatically
41
project.add_package_to_pipfile("requests", "requests>=2.25.0")
42

43
# Get environment and check installations
44
env = project.environment
45
installed = env.get_installed_packages()
46
```
47

48
CLI usage (typical workflow):
49
```bash
50
# Create and manage projects
51
pipenv install requests              # Install and add to Pipfile
52
pipenv install pytest --dev         # Install dev dependency
53
pipenv shell                         # Activate environment
54
pipenv run python script.py         # Run command in environment
55
pipenv lock                          # Generate lock file
56
pipenv sync                          # Install from lock file
57
```
58

59
## Architecture
60

61
Pipenv provides both a command-line interface and programmatic API:
62

63
- **CLI Layer**: Click-based command interface with 15+ commands
64
- **Project Layer**: Core Project class managing Pipfiles, lockfiles, and environments
65
- **Environment Layer**: Virtual environment management and package operations
66
- **Utility Layer**: File operations, dependency parsing, shell integration
67
- **Routine Layer**: High-level operations for install, sync, update, etc.
68

69
## Capabilities
70

71
### Command Line Interface
72

73
Complete CLI with 15 commands for managing Python projects including installation, environment management, dependency resolution, and project operations.
74

75
```python { .api }
76
def cli():
77
    """Main CLI entry point with global options and subcommands."""
78

79
# Main commands
80
def install(*packages, **options): ...
81
def uninstall(*packages, **options): ...
82
def lock(**options): ...
83
def sync(**options): ...
84
def shell(**options): ...
85
def run(*command, **options): ...
86
```
87

88
[Command Line Interface](./cli.md)
89

90
### Project Management
91

92
Core Project class for programmatic management of Pipfiles, lockfiles, and project metadata. Handles file operations, package tracking, and project configuration.
93

94
```python { .api }
95
class Project:
96
    def __init__(self, python_version=None, chdir=True): ...
97
    def add_package_to_pipfile(self, package, pip_line, dev=False, category=None): ...
98
    def remove_package_from_pipfile(self, package_name, category): ...
99
    def load_lockfile(self, expand_env_vars=True): ...
100
    def write_lockfile(self, content): ...
101
    def create_pipfile(self, python=None): ...
102
    
103
    # Properties
104
    name: str
105
    pipfile_location: str
106
    lockfile_location: str
107
    virtualenv_location: str
108
    parsed_pipfile: dict
109
    packages: dict
110
    dev_packages: dict
111
```
112

113
[Project Management](./project.md)
114

115
### Environment Management
116

117
Virtual environment operations including package installation, version checking, and environment activation. Manages Python interpreters and installed packages.
118

119
```python { .api }
120
class Environment:
121
    def __init__(self, prefix, python=None, is_venv=False): ...
122
    def get_installed_packages(self) -> list: ...
123
    def get_outdated_packages(self, pre: bool = False): ...
124
    def is_installed(self, pkgname): ...
125
    def is_satisfied(self, req): ...
126
    def activated(self): ...  # Context manager
127
    
128
    # Properties
129
    python: str
130
    prefix: str
131
    python_version: str
132
    sys_path: list
133
```
134

135
[Environment Management](./environment.md)
136

137
### Configuration Management
138

139
Environment variable-based configuration system controlling pipenv behavior. Provides access to all configuration options and settings.
140

141
```python { .api }
142
class Setting:
143
    # Key properties
144
    PIPENV_CACHE_DIR: str
145
    PIPENV_VENV_IN_PROJECT: bool
146
    PIPENV_VERBOSE: bool
147
    PIPENV_QUIET: bool
148
    PIPENV_SKIP_LOCK: bool
149
    PIPENV_MAX_DEPTH: int
150
    # ... and many more configuration options
151
```
152

153
[Configuration](./configuration.md)
154

155
### Utilities and Helpers
156

157
Utility functions for dependency parsing, shell operations, file handling, script parsing, and system integration. Includes constants, type definitions, and helper functions.
158

159
```python { .api }
160
# Dependencies
161
def get_version(pipfile_entry): ...
162
def python_version(path_to_python): ...
163
def determine_package_name(): ...
164

165
# Shell utilities
166
def make_posix(path: str) -> str: ...
167
def chdir(path): ...  # Context manager
168
def load_path(python): ...
169

170
# File utilities
171
def find_pipfile(max_depth=3): ...
172
def ensure_pipfile(): ...
173

174
# Script parsing
175
class Script:
176
    @classmethod
177
    def parse(cls, value): ...
178
    def cmdify(self): ...
179
```
180

181
[Utilities](./utilities.md)
182

183
### Exception Handling
184

185
Comprehensive exception hierarchy for handling various error conditions including file operations, command execution, and dependency resolution failures.
186

187
```python { .api }
188
class PipenvException(Exception): ...
189
class PipenvCmdError(PipenvException): ...
190
class PipenvUsageError(PipenvException): ...
191
class PipfileNotFound(PipenvException): ...
192
class VirtualenvCreationException(PipenvException): ...
193
class InstallError(PipenvException): ...
194
class ResolutionFailure(PipenvException): ...
195
```
196

197
[Exception Handling](./exceptions.md)
198

199
### Routines
200

201
High-level operations that implement core pipenv functionality. These functions provide the main business logic for install, lock, sync, and other operations.
202

203
```python { .api }
204
def do_install(project, **kwargs): ...
205
def do_lock(project, **kwargs): ...
206
def do_sync(project, **kwargs): ...
207
def do_uninstall(project, **kwargs): ...
208
def do_shell(project, **kwargs): ...
209
def do_run(project, command, args, **kwargs): ...
210
```
211

212
[Routines](./routines.md)
213

214
## Version Information
215

216
```python { .api }
217
__version__: str  # "2025.0.4"
218
```
219

220
Access version information:
221
```python
222
from pipenv import __version__
223
print(__version__)  # "2025.0.4"
224
```