uv_unix/
resource_limits.rs

1//! Helper for adjusting Unix resource limits.
2//!
3//! Linux has a historically low default limit of 1024 open file descriptors per process.
4//! macOS also defaults to a low soft limit (typically 256), though its hard limit is much
5//! higher. On modern multi-core machines, these low defaults can cause "too many open files"
6//! errors because uv infers concurrency limits from CPU count and may schedule more concurrent
7//! work than the default file descriptor limit allows.
8//!
9//! This module attempts to raise the soft limit to the hard limit at startup to avoid these
10//! errors without requiring users to manually configure their shell's `ulimit` settings.
11//! The raised limit is inherited by child processes, which is important for commands like
12//! `uv run` that spawn Python interpreters.
13//!
14//! See: <https://github.com/astral-sh/uv/issues/16999>
15
16use nix::errno::Errno;
17use nix::sys::resource::{RLIM_INFINITY, Resource, getrlimit, rlim_t, setrlimit};
18use thiserror::Error;
19
20/// Errors that can occur when adjusting resource limits.
21#[derive(Debug, Error)]
22pub enum OpenFileLimitError {
23    #[error("failed to get open file limit: {}", .0.desc())]
24    GetLimitFailed(Errno),
25
26    #[error("encountered unexpected negative soft limit: {value}")]
27    NegativeSoftLimit { value: rlim_t },
28
29    #[error("soft limit ({current}) already meets the target ({target})")]
30    AlreadySufficient { current: u64, target: u64 },
31
32    #[error("requested open file limit ({target}) exceeds the hard limit ({hard})")]
33    ExceedsHardLimit { target: u64, hard: rlim_t },
34
35    #[error("failed to set open file limit from {current} to {target}: {}", source.desc())]
36    SetLimitFailed {
37        current: u64,
38        target: u64,
39        source: Errno,
40    },
41}
42
43/// Maximum file descriptor limit to request.
44///
45/// We cap at 0x100000 (1,048,576) to match the typical Linux default (`/proc/sys/fs/nr_open`)
46/// and to avoid issues with extremely high limits.
47///
48/// `OpenJDK` uses this same cap because:
49///
50/// 1. Some code breaks if `RLIMIT_NOFILE` exceeds `i32::MAX` (despite the type being `u64`)
51/// 2. Code that iterates over all possible FDs, e.g., to close them, can timeout
52///
53/// See: <https://bugs.openjdk.org/browse/JDK-8324577>
54/// See: <https://github.com/oracle/graal/issues/11136>
55///
56/// Note: `rlim_t` is platform-specific (`u64` on Linux/macOS, `i64` on FreeBSD).
57const MAX_NOFILE_LIMIT: rlim_t = 0x0010_0000;
58
59/// Attempt to raise the open file descriptor limit to the maximum allowed.
60///
61/// This function tries to set the soft limit to `min(hard_limit, 0x100000)`. If the operation
62/// fails, it returns an error since the default limits may still be sufficient for the
63/// current workload.
64///
65/// Returns [`Ok`] with the new soft limit on successful adjustment, or an appropriate
66/// [`OpenFileLimitError`] if adjustment failed.
67///
68/// Note the type of `rlim_t` is platform-specific (`u64` on Linux/macOS, `i64` on FreeBSD), but
69/// this function always returns a [`u64`].
70pub fn adjust_open_file_limit() -> Result<u64, OpenFileLimitError> {
71    let (soft, hard) =
72        getrlimit(Resource::RLIMIT_NOFILE).map_err(OpenFileLimitError::GetLimitFailed)?;
73
74    // Convert `rlim_t` to `u64`. On FreeBSD, `rlim_t` is `i64` which may fail.
75    // On Linux and macOS, `rlim_t` is a `u64`, and the conversion is infallible.
76    let Some(soft) = rlim_t_to_u64(soft) else {
77        return Err(OpenFileLimitError::NegativeSoftLimit { value: soft });
78    };
79
80    // Cap the target limit to avoid issues with extremely high values.
81    // If hard is negative or exceeds MAX_NOFILE_LIMIT, use MAX_NOFILE_LIMIT.
82    #[expect(clippy::unnecessary_cast)]
83    let target = rlim_t_to_u64(hard.min(MAX_NOFILE_LIMIT)).unwrap_or(MAX_NOFILE_LIMIT as u64);
84
85    if soft >= target {
86        return Err(OpenFileLimitError::AlreadySufficient {
87            current: soft,
88            target,
89        });
90    }
91
92    // Try to raise the soft limit to the target.
93    // Safe because target <= MAX_NOFILE_LIMIT which fits in both i64 and u64.
94    let target_rlim = target as rlim_t;
95
96    set_open_file_limit_to(soft, target, target_rlim, hard)
97}
98
99/// Set the soft open-file descriptor limit while preserving the hard limit.
100pub fn set_open_file_limit(target: u32) -> Result<u64, OpenFileLimitError> {
101    let (soft, hard) =
102        getrlimit(Resource::RLIMIT_NOFILE).map_err(OpenFileLimitError::GetLimitFailed)?;
103    let Some(soft) = rlim_t_to_u64(soft) else {
104        return Err(OpenFileLimitError::NegativeSoftLimit { value: soft });
105    };
106
107    let target_rlim = rlim_t::from(target);
108    let target = u64::from(target);
109    if hard != RLIM_INFINITY && target_rlim > hard {
110        return Err(OpenFileLimitError::ExceedsHardLimit { target, hard });
111    }
112
113    set_open_file_limit_to(soft, target, target_rlim, hard)
114}
115
116/// Update the soft open-file descriptor limit while preserving the hard limit.
117fn set_open_file_limit_to(
118    current: u64,
119    target: u64,
120    target_rlim: rlim_t,
121    hard: rlim_t,
122) -> Result<u64, OpenFileLimitError> {
123    setrlimit(Resource::RLIMIT_NOFILE, target_rlim, hard).map_err(|err| {
124        OpenFileLimitError::SetLimitFailed {
125            current,
126            target,
127            source: err,
128        }
129    })?;
130
131    Ok(target)
132}
133
134/// Convert `rlim_t` to `u64`, returning `None` if negative.
135///
136/// On Linux/macOS, `rlim_t` is `u64` so this always succeeds.
137/// On FreeBSD, `rlim_t` is `i64` so negative values return `None`.
138#[expect(clippy::useless_conversion)]
139fn rlim_t_to_u64(value: rlim_t) -> Option<u64> {
140    u64::try_from(value).ok()
141}
uv_unix/resource_limits.rs

uv_unix/
resource_limits.rs
