0
# Command Line Interface
1

2
Complete command-line profiling tool providing three main subcommands for different profiling scenarios. Supports extensive configuration for production environments, development workflows, and advanced profiling scenarios.
3

4
## Capabilities
5

6
### Record Subcommand
7

8
Records profiling samples to files in various formats. Creates flame graphs, speedscope profiles, and other visualization formats for offline analysis.
9

10
```bash { .api }
11
py-spy record [OPTIONS] [TARGET]
12

13
# Record to flamegraph (SVG)
14
py-spy record -o profile.svg --pid 12345
15
py-spy record -o profile.svg -- python myprogram.py
16

17
# Record to speedscope JSON
18
py-spy record -f speedscope -o profile.json --pid 12345
19

20
# Record to Chrome trace format
21
py-spy record -f chrometrace -o trace.json --pid 12345
22

23
# Record raw flamegraph data
24
py-spy record -f raw -o profile.txt --pid 12345
25
```
26

27
**Target Options:**
28
- `--pid PID` or `-p PID`: Profile existing process by PID (decimal or hex)
29
- `-- PYTHON_PROGRAM [ARGS...]`: Launch and profile new Python program
30

31
**Output Options:**
32
- `--output FILE` or `-o FILE`: Output filename (auto-generated if not specified)
33
- `--format FORMAT` or `-f FORMAT`: Output format (flamegraph, speedscope, chrometrace, raw)
34

35
**Recording Options:**
36
- `--duration SECONDS` or `-d SECONDS`: Recording duration (unlimited if not specified)
37
- `--rate RATE` or `-r RATE`: Sampling rate in Hz (default: 100)
38

39
### Top Subcommand
40

41
Provides live console view of profiling data, similar to Unix `top` command. Updates in real-time showing function call distribution and thread activity.
42

43
```bash { .api }
44
py-spy top [OPTIONS] [TARGET]
45

46
# Live view of existing process
47
py-spy top --pid 12345
48

49
# Live view of new Python program
50
py-spy top -- python myprogram.py
51
```
52

53
**Display Options:**
54
- `--rate RATE` or `-r RATE`: Sampling rate in Hz (default: 100)
55
- `--refresh-seconds SECONDS`: Display refresh interval (default: 1.0)
56

57
### Dump Subcommand
58

59
Takes single snapshot of call stacks for all threads. Useful for debugging hung processes or getting immediate stack trace information.
60

61
```bash { .api }
62
py-spy dump [OPTIONS] [TARGET]
63

64
# Simple stack dump
65
py-spy dump --pid 12345
66

67
# Dump with local variables
68
py-spy dump --locals --pid 12345
69

70
# JSON format output
71
py-spy dump --json --pid 12345
72
```
73

74
**Output Options:**
75
- `--locals`: Include local variables in stack frames
76
- `--json`: Output in JSON format
77

78
## Global Options
79

80
### Process Selection
81

82
```bash { .api }
83
--pid PID, -p PID
84
    # Process ID to profile (decimal or hex)
85
    py-spy record --pid 12345 -o profile.svg
86
    py-spy record --pid 0x3039 -o profile.svg
87

88
-- PYTHON_PROGRAM [ARGS...]
89
    # Launch and profile new Python program
90
    py-spy record -o profile.svg -- python -m mymodule --arg value
91
    py-spy top -- python script.py arg1 arg2
92
```
93

94
### Profiling Mode Options
95

96
```bash { .api }
97
--native, -n
98
    # Include native C/C++/Cython stack traces
99
    py-spy record --native -o profile.svg --pid 12345
100

101
--nonblocking
102
    # Non-blocking sampling (reduced performance impact)
103
    py-spy record --nonblocking -o profile.svg --pid 12345
104

105
--subprocesses, -s
106
    # Profile child processes and subprocess spawns
107
    py-spy record --subprocesses -o profile.svg --pid 12345
108

109
--gil
110
    # Only show threads holding the Global Interpreter Lock
111
    py-spy top --gil --pid 12345
112

113
--idle, -i
114
    # Include idle/sleeping threads in results
115
    py-spy record --idle -o profile.svg --pid 12345
116
```
117

118
### Display and Formatting Options
119

120
```bash { .api }
121
--full-filenames
122
    # Show full Python file paths instead of shortened versions
123
    py-spy dump --full-filenames --pid 12345
124

125
--include-thread-ids
126
    # Include thread IDs in flamegraph output
127
    py-spy record --include-thread-ids -o profile.svg --pid 12345
128

129
--show-line-numbers
130
    # Include line numbers in stack traces
131
    py-spy dump --show-line-numbers --pid 12345
132
```
133

134
### Linux-Specific Options
135

136
```bash { .api }
137
--core CORE_FILE
138
    # Analyze Python process from core dump (Linux only)
139
    py-spy dump --core /path/to/core.dump
140
```
141

142
## Platform-Specific Requirements
143

144
### macOS
145
```bash
146
# Requires root privileges
147
sudo py-spy record -o profile.svg --pid 12345
148
```
149

150
### Docker Containers
151
```bash
152
# Requires SYS_PTRACE capability
153
docker run --cap-add=SYS_PTRACE image_name
154
# Or in docker-compose.yml:
155
# cap_add:
156
#   - SYS_PTRACE
157
```
158

159
### Kubernetes
160
```yaml
161
securityContext:
162
  capabilities:
163
    add:
164
    - SYS_PTRACE
165
```
166

167
## Usage Examples
168

169
### Development Workflow
170

171
```bash
172
# Profile development server
173
py-spy record -o dev-profile.svg -- python manage.py runserver
174

175
# Monitor performance during development
176
py-spy top -- python myapp.py
177

178
# Debug hanging script
179
py-spy dump --locals --pid 12345
180
```
181

182
### Production Profiling
183

184
```bash
185
# Low-impact production profiling
186
py-spy record --nonblocking -d 30 -o prod-profile.svg --pid 12345
187

188
# Profile with subprocesses (e.g., gunicorn workers)
189
py-spy record --subprocesses -d 60 -o worker-profile.svg --pid 12345
190

191
# Profile only GIL-holding threads
192
py-spy record --gil -d 30 -o gil-profile.svg --pid 12345
193
```
194

195
### Advanced Analysis
196

197
```bash
198
# Include native extensions (C/C++/Cython)
199
py-spy record --native -o native-profile.svg --pid 12345
200

201
# Generate speedscope format for detailed analysis
202
py-spy record -f speedscope -o analysis.json --pid 12345
203

204
# High-frequency sampling for detailed profiling
205
py-spy record -r 1000 -d 10 -o detailed.svg --pid 12345
206
```
207

208
### Comparative Analysis
209

210
```bash
211
# Before optimization
212
py-spy record -o before.svg -- python myapp.py input.txt
213

214
# After optimization  
215
py-spy record -o after.svg -- python myapp.py input.txt
216

217
# Compare using speedscope format
218
py-spy record -f speedscope -o before.json -- python myapp.py input.txt
219
py-spy record -f speedscope -o after.json -- python myapp.py input.txt
220
```
221

222
## Exit Codes
223

224
- `0`: Successful completion
225
- `1`: Error occurred (permission denied, process not found, etc.)
226

227
## Environment Variables
228

229
```bash
230
# Force colored output when piping to pager
231
CLICOLOR_FORCE=1 py-spy top --pid 12345 | less -R
232
```