Install & Compatibility
Where this runs
tested against v1.5.0 · 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
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 16.1s · import 0.468s · 388MB
404MB installed
● package 404MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
read
✓ from obspy import read
Stream
✓ from obspy.core import Stream
✗ from obspy import Stream
While `from obspy import Stream` works via internal aliases, `from obspy.core import Stream` is the canonical path and clarifies its origin.
Trace
✓ from obspy.core import Trace
✗ from obspy import Trace
Similar to `Stream`, `from obspy.core import Trace` is the canonical path.
UTCDateTime
✓ from obspy import UTCDateTime
filter
✓ from obspy.signal.filter import filter_function
✗ from obspy.signal.util import filter_function
Many signal processing utilities were reorganized or moved to `obspy.signal.filter` in ObsPy 1.1.0. Check `obspy.signal` documentation for specific function locations.
This quickstart demonstrates how to read seismic data using `obspy.read()`, access `Stream` and `Trace` objects, and perform a basic filter operation. It also includes error handling for network issues and creates a dummy stream if needed. Note that plotting functionality requires the `matplotlib` library.
from obspy import read, UTCDateTime
import os
# ObsPy often requires C-compiled dependencies for full functionality and speed.
# It is highly recommended to install via Anaconda/Miniconda:
# conda install -c conda-forge obspy
# Example: Reading a MiniSEED file from a URL
try:
# This URL provides a small example MiniSEED file.
# For local files, replace with your path: st = read("path/to/your/file.mseed")
st = read("https://examples.obspy.org/BW.KW1..EHZ.D.2010.010.mseed")
print(f"\nSuccessfully loaded stream: {st}")
# Accessing the first trace in the stream
trace = st[0]
print(f"First trace metadata: {trace.stats}")
print(f"Start time: {trace.stats.starttime}, End time: {trace.stats.endtime}")
print(f"Sampling rate: {trace.stats.sampling_rate} Hz")
print(f"Number of samples: {trace.stats.npts}")
# Accessing the data array (NumPy array)
print(f"First 5 data points: {trace.data[:5]}")
# Apply a basic filter (requires scipy)
st.filter('lowpass', freq=0.5)
print(f"\nStream after lowpass filter: {st}")
# For plotting, matplotlib is required:
# try:
# st.plot()
# print("Plot generated (if matplotlib installed).")
# except ImportError:
# print("Install 'matplotlib' (pip install matplotlib) to enable plotting.")
except Exception as e:
print(f"\nFailed to read example data. Error: {e}")
print("Please ensure you have an active internet connection or try a local file.")
# Fallback to creating a dummy stream if download fails
from obspy.core import Stream, Trace
import numpy as np
print("Creating a dummy stream for demonstration...")
UTC_DT = UTCDateTime("2023-01-01T00:00:00.000Z")
stats = {'network': 'XX', 'station': 'DUM', 'location': '00',
'channel': 'BHZ', 'starttime': UTC_DT, 'delta': 0.01,
'sampling_rate': 100.0, 'npts': 1000}
dummy_trace = Trace(data=np.random.rand(stats['npts']), header=stats)
dummy_st = Stream([dummy_trace])
print(f"Dummy stream created: {dummy_st}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'obspy'
The ObsPy library is not installed in the current Python environment.
fixInstall ObsPy using `pip install obspy` or `conda install -c conda-forge obspy`.
ImportError: No module named 'matplotlib'
Attempting to use plotting methods (e.g., `Stream.plot()`) without `matplotlib` installed.
fixInstall `matplotlib` in your environment: `pip install matplotlib` or `conda install matplotlib`.
IOError: [Errno 2] No such file or directory: 'myfile.mseed'
The `obspy.read()` function cannot find the specified file, likely due to an incorrect file path, a misspelled filename, or the file not existing at the given location.
fixDouble-check the file path and filename. Ensure the file exists and the path is absolute or correct relative to your script's working directory. Use `os.path.exists('myfile.mseed')` to verify. TypeError: unsupported operand type(s) for +: 'str' and 'UTCDateTime'
Attempting to concatenate a string and an `obspy.UTCDateTime` object without explicitly converting the `UTCDateTime` to a string first.
fixExplicitly convert `UTCDateTime` objects to strings using `str()` or `strftime()` before concatenating them with other strings, e.g., `print('Time: ' + str(my_datetime))`. AttributeError: 'Stream' object has no attribute 'some_method_from_old_version'
Attempting to use an API method that has been removed, renamed, or moved to a different module in a newer ObsPy version.
fixConsult the ObsPy documentation (docs.obspy.org) for the version you are using to find the correct method name or its new location. This often occurs when migrating code from older ObsPy versions (pre-1.0) or when specific functions were refactored into submodules.
Upgrade
Version history
1.5.0latest on PyPI · released Mar 13, 2026
Audit
Dependencies
matplotliboptionalRequired for plotting functionality (e.g., `Stream.plot()`, `Trace.plot()`).
lxmloptionalRequired for reading/writing StationXML metadata.
scipyrequiredCore dependency for signal processing functions.
numpyrequiredCore dependency for numerical operations and data arrays.